@blotout/qinto-cli 0.1.14 → 0.1.16

package/README.md

@@ -128,6 +128,48 @@ qinto app publish --site example.com          # …and install it on a site
 qinto app status my-app --site example.com    # desired vs deployed state
 ```
 
+### Get a developer organization
+
+**A team is not an organization.** A team owns sites and installs apps; an organization owns the apps you write. Membership in a
+team — even as its owner — gives you nothing in any organization, and switching the active team does not change that. Until your
+account belongs to an organization, `qinto app register` refuses with one of:
+
+```
+This credential has no organizations. Log in with `qinto login` first.
+Organization <name> is not available to this credential.
+```
+
+Neither is fixed by logging in again. `qinto whoami` says which case you are in — it prints an `Organizations:` block listing each
+organization and your role in it, and prints no such block when you belong to none.
+
+**The CLI cannot create an organization; the Qinto platform does.** Open it in a browser and click **Developer** in the sidebar,
+or go straight to the Developer area:
+
+| Environment | Developer area |
+| --- | --- |
+| `production` | `https://portal.qinto.io/developer` |
+| `sandbox` | `https://portal.qinto.tech/developer` |
+
+**Opening that page is the whole step.** The first visit creates a personal organization named after your email address and makes
+you its owner — nothing is approved, granted, or provisioned by anyone else. Use the organization switcher at the top of the
+Developer sidebar to rename it, or **Create organization** to add another (one per customer or product, say).
+
+To publish under an organization that already exists — a company's, rather than your own — one of its owners invites you under
+**Developer → Organization members** and you accept the emailed link. An organization cannot be joined by naming its id.
+
+Back in the terminal the organization appears immediately: the CLI reads it from the API on every call, so **no new login is
+needed**. Pass it by id or name with `--org`.
+
+```sh
+qinto whoami                                    # confirm the Organizations block now lists it
+qinto app register ./my-app --org "Acme Inc."
+```
+
+If `whoami` still lists no organization when you know you belong to one, the login is too narrow rather than the organization
+missing: your account identity needs the `profile` scope and every `qinto app` command needs `developer`. A plain `qinto login`
+requests both, a login narrowed with `--scopes` may not, and `whoami` names it — `Authenticated with an OAuth token without the
+profile scope.` Run `qinto login --reauthorize` and grant them.
+
 ### Scaffold — `qinto app create [dir]`
 
 Asks for the app name, proposes a slug derived from it that you confirm or replace, and asks which template to start from. It
@@ -168,8 +210,9 @@ declares only its build tooling.
 
 ### Register — `qinto app register [dir]`
 
-Registers the slug under an organization. `create --register` calls it for you; run it directly to register an app you scaffolded
-earlier or wrote by hand. The slug is immutable and unique inside the organization.
+Registers the slug under an organization — see [Get a developer organization](#get-a-developer-organization) when you have none.
+`create --register` calls it for you; run it directly to register an app you scaffolded earlier or wrote by hand. The slug is
+immutable and unique inside the organization.
 
 The slug, name, and description come from `qinto.app.jsonc` — the one in `dir`, or the one in the current directory when you pass
 no `dir`. Pass `--slug`, `--name`, and `--description` only for an app that has no manifest yet; alongside a manifest they are
@@ -268,6 +311,7 @@ are namespaced by its slug, so two apps declaring a `d1` called `ledger` get a d
 | `--reset` | Discard this directory's local installs, variables, secrets and stored data first. |
 | `--tunnel` | Expose the site worker on a fresh `trycloudflare.com` hostname, so a vendor webhook can reach its endpoints. |
 | `--tunnel-name <name>` | Expose it through this named Cloudflare Tunnel instead, for a hostname that survives a restart. |
+| `--tunnel-hours <hours>` | Close the tunnel after this many hours, instead of leaving it open until `app dev` stops. |
 | `--no-input` | Disable all interactive prompts, mounting every app found. |
 
 All four listeners bind `127.0.0.1` only.
@@ -300,9 +344,16 @@ register with the vendor and keeps the loopback one beside it for `curl`.
 
 `cloudflared` is downloaded and cached on first use, unless you already have one on `PATH` or at `CLOUDFLARED_PATH`.
 
-**The tunnel closes after an hour.** It is a public door onto your machine, and an `app dev` left running overnight would hold it
-open until you noticed. `dev` says how long is left every ten minutes; press `a` then Enter to add an hour, up to three hours from
-now. When it closes, the public URL stops being advertised and the loopback one carries on.
+**The tunnel closes when `app dev` does.** It is a public door onto your machine, so quitting `dev` is what shuts it: there is no
+separate clock, and a session left running overnight holds the door open until you stop it. Cloudflare places no limit of its own,
+so a named tunnel will happily run for days.
+
+**`--tunnel-hours <hours>` closes it earlier.** Give it a deadline and `dev` says how long is left every ten minutes; press `a`
+then Enter to add an hour, as often as you like. When it closes, the public URL stops being advertised and the loopback one
+carries on. Fractions work, so `--tunnel-hours 0.5` is half an hour. Nothing caps the number.
+
+For a run measured in days, use `--tunnel-name`. Cloudflare gives `trycloudflare.com` no uptime guarantee and caps it at 200
+in-flight requests, so a quick tunnel is a debug aid rather than something to leave up over a weekend.
 
 **A hostname that survives a restart — `--tunnel-name <name>`.** A quick tunnel is free and needs no account, but its hostname is
 new on every run, so a vendor has to be told the new one each time. A named tunnel keeps one hostname. `dev` reads it from **your