carlos / platform Public

docs: the environment-store example did not run

Three mistakes in one block, all mine. `carlos env` takes its flags after
the subverb and needs --app, so the line as written was a usage error. And
the instance was created at the customer's own hostname, which an instance
host cannot be: it sits at a free label under the account's platform domain,
and the customer hostname is attached to it afterwards with `domains attach`.

The docsite gate did not catch it because it checks that a heading exists and
that fenced examples name real verbs — not that the flags parse. Worth
knowing about that gate's edge.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

James Adam pushed by james@keymail.dev 1 month ago 8dd2ceeaaf2bff24526d8ce906b794a74fb5cb1d parent 664482a

1 file changed, +8 −2

docs/site/cli.md +8 −2

diff --git a/docs/site/cli.md b/docs/site/cli.md

index 95ef33dc4..3df903a7b 100644

--- a/docs/site/cli.md

+++ b/docs/site/cli.md

@@ -847,12 +847,18 @@ only the instances bound to it can reach it. An instance gets a bucket of its

own by being the only instance bound to its environment.

```sh

-carlos env --environment acme set APP_ORIGIN=https://acme.example.com

+carlos env set --app hello --environment acme APP_ORIGIN=https://acme.example.com

+carlos instances create --app hello --host acme.bab.oncarlos.com --channel edge --environment acme

+carlos domains attach --app hello --route acme.bab.oncarlos.com acme.example.com

carlos store create --app hello --environment acme

-carlos instances create --app hello --host acme.example.com --environment acme

carlos store status --app hello --environment acme

```

+The instance sits at a free label under the account's platform domain; the

+customer's own hostname is attached to it afterwards. `--route` is required

+on `domains attach` once an app has more than one instance — the console

+refuses to guess which one a hostname belongs to.

`create`, `status`, `grant` and `rotate` all take `--environment`, and each

acts on that store alone. Without it they act on the app's own store, exactly

as they always have — nothing about an app with no environment stores changes.