From 4e7e91fd2e6174996b1abacee81e3318a773b5f9 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 2 Oct 2026 05:12:09 +0000 Subject: [PATCH 1/2] docs(cli): README states the global flags, the os plugin group and two command rows as os does The README listed -v/-h as global short flags (both exit 2), said there is no os plugin command group (build/sign/publish are registered), described os init as always using the current directory, and os dev as hot reload. Claude-Session: https://claude.ai/code/session_018gA1pE6eJtwHhqx72G8U9X Co-authored-by: Claude --- .changeset/21310-cli-readme-flags.md | 15 +++++++++++++++ packages/cli/README.md | 25 ++++++++++++++++++++----- 2 files changed, 35 insertions(+), 5 deletions(-) create mode 100644 .changeset/21310-cli-readme-flags.md diff --git a/.changeset/21310-cli-readme-flags.md b/.changeset/21310-cli-readme-flags.md new file mode 100644 index 00000000000..130243f2125 --- /dev/null +++ b/.changeset/21310-cli-readme-flags.md @@ -0,0 +1,15 @@ +--- +'@objectstack/cli': patch +--- + +The published README now describes the `os` that ships. Three of its claims were false. + +Clause-②: no + +**Short flags.** The README listed `-v, --version` and `-h, --help` as global options. `os -v` and `os -h` exit 2 with `command -v not found` / `command -h not found`, because only `--version` and `--help` are registered. It now lists `--version` and `--help` alone and says there is no short form. `-v` already belongs to commands of their own: it is `--verbose` on `os dev`, `os serve`, `os start` and `os doctor`, and `--version` on `os package publish` and `os package install`. + +**The `os plugin` group.** The README said there is no `os plugin` command group. `os plugin build`, `os plugin sign` and `os plugin publish` are registered, and the README now lists them. It also says the group has no `install`, and that `os plugin` is a different thing from `os plugins`, which is not a command. + +**Two command rows.** `os init [name]` creates a new directory of that name when a name is given, so it no longer says "in the current directory" for every case. `os dev` restarts the server after each rebuild, so it no longer says "with hot reload". + +**What changes for an operator.** Nothing at runtime. No command, flag, exit code or help page changes. diff --git a/packages/cli/README.md b/packages/cli/README.md index 76ea8c0d924..cdf836d546b 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -39,8 +39,8 @@ os compile | Command | Description | |---------|-------------| -| `os init [name]` | Initialize a new ObjectStack project in the current directory | -| `os dev [package]` | Start development mode with hot reload | +| `os init [name]` | Initialize a new ObjectStack project — in a new directory of that name when `name` is given, otherwise in the current directory | +| `os dev [package]` | Start development mode — watch sources, rebuild the artifact, and restart the server on change | | `os serve [config]` | Start the ObjectStack server with plugin auto-detection | ### Build & Validate @@ -112,7 +112,17 @@ review) or `--auto-approve` (platform admins only). Set `OS_CLOUD_URL` (or ### Plugin Management -Runtime plugins (declared in `objectstack.config.ts` `plugins`) are loaded automatically by `os serve` / `os dev`. There is no `os plugin` command group in v1; runtime plugins are bundled into the build artifact. To distribute a build, publish it as a package with `os package publish` (see [Cloud — publish & install](#cloud--publish--install)); the `os environments bind --artifact dist/objectstack.json` path still binds an artifact directly into an environment without going through the package registry. +Runtime plugins (declared in `objectstack.config.ts` `plugins`) are loaded automatically by `os serve` / `os dev`. Runtime plugins are bundled into the build artifact. To distribute a build, publish it as a package with `os package publish` (see [Cloud — publish & install](#cloud--publish--install)); the `os environments bind --artifact dist/objectstack.json` path still binds an artifact directly into an environment without going through the package registry. + +A code-bearing plugin — a directory carrying an `objectstack.plugin.json` manifest — is packaged and shipped through the `os plugin` command group (ADR-0025 §3.4, build → sign → publish): + +| Command | Description | +|---------|-------------| +| `os plugin build [dir]` | Compile a plugin into a signed-ready `.osplugin` artifact (`--entry`, `--out`, `--minify`) | +| `os plugin sign --key ` | Sign a built `.osplugin` with a publisher Ed25519 key, writing a detached `.sig` | +| `os plugin publish [artifact]` | Publish a signed `.osplugin` to ObjectStack Cloud | + +The group has no `install`: ADR-0025 records the code-plugin install half (download, verify, materialize, load) as not yet implemented. `os plugin` (singular) is unrelated to `os plugins` (plural), oclif's plugin manager, which this package does not ship — see [`os plugins` and `os help`](#os-plugins-and-os-help-not-commands). ### Quality @@ -176,8 +186,13 @@ Common variables: `OS_DATABASE_URL`, `OS_DATABASE_DRIVER`, ### Global -- `-v, --version` — Show version number -- `-h, --help` — Show help +- `--version` — Show version number +- `--help` — Show help (`os --help`, or `os --help` for one command) + +There are no short forms: `os -h` and `os -v` exit 2 with `command -h not found` / +`command -v not found`. `-v` is a command's own flag instead — `--verbose` on `os dev`, +`os serve`, `os start` and `os doctor`, `--version ` on `os package publish` and +`os package install`. ### `os init` From ebe37973517f5f2c6e96cc7a34ef15270fe31d8a Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 2 Oct 2026 06:43:35 +0000 Subject: [PATCH 2/2] docs(cli): README states each cloud command's credential source and flags, and os serve --ui as the help does Patch round 1. The Cloud section said every cloud command reads os cloud login's session or --token/OS_CLOUD_API_KEY and --server/OS_CLOUD_URL; os environments * take -u/--url and -t/--token (env OS_TOKEN) and use the os login session instead. os serve --ui enables the bundled Console portal, not "Studio UI". The changeset now counts five false claims. Claude-Session: https://claude.ai/code/session_018gA1pE6eJtwHhqx72G8U9X Co-authored-by: Claude --- .changeset/21310-cli-readme-flags.md | 14 +++++------ packages/cli/README.md | 37 ++++++++++++++++++++++------ 2 files changed, 36 insertions(+), 15 deletions(-) diff --git a/.changeset/21310-cli-readme-flags.md b/.changeset/21310-cli-readme-flags.md index 130243f2125..cdebf1609df 100644 --- a/.changeset/21310-cli-readme-flags.md +++ b/.changeset/21310-cli-readme-flags.md @@ -2,14 +2,14 @@ '@objectstack/cli': patch --- -The published README now describes the `os` that ships. Three of its claims were false. +The published README now describes the `os` that ships. Five things it said were false. Clause-②: no -**Short flags.** The README listed `-v, --version` and `-h, --help` as global options. `os -v` and `os -h` exit 2 with `command -v not found` / `command -h not found`, because only `--version` and `--help` are registered. It now lists `--version` and `--help` alone and says there is no short form. `-v` already belongs to commands of their own: it is `--verbose` on `os dev`, `os serve`, `os start` and `os doctor`, and `--version` on `os package publish` and `os package install`. +- **Short flags.** The README listed `-v, --version` and `-h, --help` as global options. `os -v` and `os -h` exit 2 with `command -v not found` / `command -h not found`, because only `--version` and `--help` are registered. It now lists `--version` and `--help` alone and says there is no short form. `-v` already belongs to commands of their own: it is `--verbose` on `os dev`, `os serve`, `os start` and `os doctor`, and `--version` on `os package publish` and `os package install`. +- **The `os plugin` group.** The README said there is no `os plugin` command group. `os plugin build`, `os plugin sign` and `os plugin publish` are registered, and the README now lists them. It also says the group has no `install`, and that `os plugin` is a different thing from `os plugins`, which is not a command. +- **Two command rows.** `os init [name]` creates a new directory of that name when a name is given, so it no longer says "in the current directory" for every case. `os dev` restarts the server after each rebuild, so it no longer says "with hot reload". +- **Cloud credentials and flags.** The README said every cloud command takes its credentials from `os cloud login` or from `--token` / `OS_CLOUD_API_KEY` and `--server` / `OS_CLOUD_URL`. That holds only for `os package publish` and `os plugin publish`. `os environments list`, `show`, `create`, `bind` and `switch` take `-u, --url` (env `OS_CLOUD_URL`) and `-t, --token` (env `OS_TOKEN`), and otherwise use the `os login` session in `~/.objectstack/credentials.json` — never the `os cloud login` session. With only `os cloud login` done they exit 1 with `Authentication required`. The README now has a per-command table, and its typical publish flow says so at the `os environments create` step. +- **`os serve --ui`.** The README said it enables "Studio UI". It enables the bundled Console portal at `/_console/` when `@object-ui/console` is installed, which is what `os serve --help` says. -**The `os plugin` group.** The README said there is no `os plugin` command group. `os plugin build`, `os plugin sign` and `os plugin publish` are registered, and the README now lists them. It also says the group has no `install`, and that `os plugin` is a different thing from `os plugins`, which is not a command. - -**Two command rows.** `os init [name]` creates a new directory of that name when a name is given, so it no longer says "in the current directory" for every case. `os dev` restarts the server after each rebuild, so it no longer says "with hot reload". - -**What changes for an operator.** Nothing at runtime. No command, flag, exit code or help page changes. +**What changes for an operator.** Nothing at runtime. No command, flag, environment variable, exit code or help page changes. diff --git a/packages/cli/README.md b/packages/cli/README.md index cdf836d546b..630688ff320 100644 --- a/packages/cli/README.md +++ b/packages/cli/README.md @@ -81,9 +81,8 @@ and keep loading through their barrel `index.ts`. ### Cloud — publish & install Push a locally-built package to ObjectStack Cloud and (optionally) install it -into one of your environments in a single command. Credentials and server URL -come from `os cloud login` (stored in `~/.objectstack/cloud.json`) or the -`--token` / `OS_CLOUD_API_KEY` and `--server` / `OS_CLOUD_URL` flags. +into one of your environments in a single command. The commands below do not +share one session or one flag spelling — see [Credentials and server URL](#credentials-and-server-url). | Command | Description | |---------|-------------| @@ -97,18 +96,40 @@ Typical flow (build → publish → install into an environment, seeding sample ```bash os compile # → dist/objectstack.json -os cloud login # one-time, stores the cloud session -os environments create --org "$ORG" --name "Dev" --activate +os cloud login # one-time; the session os package publish reads +os environments create --org "$ORG" --name "Dev" --activate # does NOT read that session — see below os package publish --env --install --seed-sample-data ``` +`os environments create` does not use the session `os cloud login` stored: give +it `--url` and `--token` (or `OS_CLOUD_URL` / `OS_TOKEN`), or an `os login` +session. Without either it exits 1 with `Authentication required`. + `os package publish` registers a `sys_package` (keyed by a reverse-domain `--manifest-id`, derived from the artifact when omitted), snapshots the artifact as a new `--version`, and — with `--env --install` — installs that version into the environment. Useful flags: `--visibility private|org| marketplace`, `--note`, and for marketplace listings `--submit` (request -review) or `--auto-approve` (platform admins only). Set `OS_CLOUD_URL` (or -`--server`) to target a non-default control plane, e.g. a staging cloud. +review) or `--auto-approve` (platform admins only). Set `OS_CLOUD_URL` to +target a non-default control plane, e.g. a staging cloud. `os cloud login`, +`os package publish` and `os environments` read it; the flag is `--server` on +`os package publish` and `--url` on the other two. + +#### Credentials and server URL + +Two stored sessions exist, and each command authenticates with one of them: + +| Command | Server URL | Token | Stored session | +|---------|------------|-------|-------------------------| +| `os cloud login` | `-u, --url` (env `OS_CLOUD_URL`, default `https://cloud.objectos.ai`) | none — `-e, --email` / `-p, --password`, or the browser device flow | writes `~/.objectstack/cloud.json` | +| `os cloud whoami` / `os cloud logout` | — | — | reads / deletes `~/.objectstack/cloud.json` | +| `os package publish`, `os plugin publish` | `-s, --server` (env `OS_CLOUD_URL`); else the URL in `cloud.json`; else `https://cloud.objectos.ai` | `-t, --token` (env `OS_CLOUD_API_KEY`, then `OS_TOKEN`) | `~/.objectstack/cloud.json` — the `os cloud login` session | +| `os environments list` / `show` / `create` / `bind` / `switch` | `-u, --url` (env `OS_CLOUD_URL`); else the URL in `credentials.json`; else `http://localhost:3000` | `-t, --token` (env `OS_TOKEN`) | `~/.objectstack/credentials.json` — the `os login` session, **not** `os cloud login`'s | + +`os package install` is not a cloud command: it installs into a running runtime +(`-r, --runtime`, env `OS_RUNTIME_URL`, default `http://localhost:3000`) and signs +in there with `--email` / `--password` (env `OS_RUNTIME_EMAIL` / +`OS_RUNTIME_PASSWORD`). ### Plugin Management @@ -215,7 +236,7 @@ There are no short forms: `os -h` and `os -v` exit 2 with `command -h not found` - `-p, --port ` — Server port. Resolution: `--port` › `$OS_PORT` › `$PORT` › `3000`. With `--dev` a busy port auto-hops to the next free one; in production mode it's a hard error (never silently drifts). - `--dev` — Run in development mode (load devPlugins, pretty logging) -- `--ui` — Enable Studio UI +- `--ui` — Enable the bundled Console portal at `/_console/` when `@object-ui/console` is installed (default: true) - `--no-server` — Skip starting HTTP server plugin ### `os generate`