@siteoshq/cli 1.12.0 → 2.0.0

package/README.md

@@ -1,7 +1,13 @@
 # SiteOS CLI
 
 `@siteoshq/cli` exposes one `siteos` binary for Auth, common Projects, Pulse, Cookie, Forms,
-Search, Trace, SEO/GEO and Integrations. This source is version 1.11.0; source changes require a separate release to reach npm.
+Search, Trace, SEO/GEO and Integrations. This source is version 2.0.0; source changes require a separate release to reach npm.
+
+CLI 2 requires `siteos project use <id-or-slug> --environment <slug>` once per repository.
+It stores only the common selection in private `projects.json`; older service bindings are not
+read or imported. Authentication and installed runtime/deployment credentials remain valid.
+Service-local `project` and `environment` commands have been removed; use `siteos project`.
+
 Node.js 22 or newer is required.
 
 ## Install and authenticate
@@ -74,7 +80,7 @@ Manage names and website URLs with `project update` and `project environment upd
 Cookie/Trace published addresses remain unchanged until explicit republication.
 
 `project use` writes one private binding keyed by real repository path and application origin in
-`~/.siteos/project-bindings.json`. It does not write a tracked global Project file. All service
+`~/.siteos/projects.json`. It does not write a tracked global Project file. All service
 management commands use this selection and their own runtime authority. An Organization mismatch
 requires selecting the Project in the active Organization again.
 
@@ -84,7 +90,7 @@ requires selecting the Project in the active Organization again.
 
 ```sh
 siteos project connect pulse --json
-siteos pulse project list --json
+siteos project status --json
 siteos pulse init
 siteos pulse validate --json
 siteos pulse test
@@ -99,8 +105,7 @@ monitoring are explicit operations. `deploy --dry-run` builds locally without up
 In a monorepo, run Pulse commands from the directory containing that website's
 `siteos.config.json`. The current source resolves deployment configuration, specs and archive
 output from that directory; private Project selection remains scoped to the Git repository.
-This fixes published CLI 1.10.0, which incorrectly bundled the repository root on deployment.
-Use a locally built CLI containing the fix until its separate npm release is available.
+Nested website deployments resolve files relative to that website while retaining the repository’s common Project selection.
 
 CLI 1.10.0 adds an optional `environmentVariables` array to each Check, for
 example `"environmentVariables": ["TEST_EMAIL", "TEST_INBOX_TOKEN"]`. Declare names only, and set
@@ -114,11 +119,11 @@ earlier published versions do not preserve these declarations. See
 ### Forms and Search
 
 ```sh
-siteos forms environment list --json
+siteos project environment list --json
 siteos forms definition check --manifest .siteos/forms/manifest.json --json
 siteos forms definition sync --environment production --manifest .siteos/forms/manifest.json --json
 siteos forms credential issue --environment production --install --json
-siteos search environment list --json
+siteos project environment list --json
 siteos search diagnostics --environment production --json
 siteos search credential issue --environment production --install --json
 siteos search indexing-credential issue --environment production --install --json
@@ -205,6 +210,10 @@ Research and GSC Insights use these commands with a matching server release:
 siteos seo research summary --json
 siteos seo research history --kind keywords --json
 siteos seo research show <run-id> --json
+siteos seo research serp show <run-id> --keyword "website analytics" --json
+siteos seo research serp ensure <run-id> --keyword "website analytics" --json
+siteos seo research serp wait <run-id> --keyword "website analytics" --json
+siteos seo research serp export <run-id> --keyword "website analytics" --format json --output ./serp-report.json --json
 siteos seo research plan --input ./research-request.json --json
 siteos seo research run --input ./research-request.json --idempotency-key <retry-key> --json
 siteos seo research wait <run-id> --json
@@ -219,6 +228,8 @@ Research supports keywords, Domain Overview (`domain`), rankings, backlinks, bra
 Domain Overview collects domain totals, up to 100 ranking keywords, pages and competitors for a market.
 `--kind domain` includes legacy `competitors` history; existing `competitors` inputs keep their original two-part plan.
 New request example: `{"kind":"domain","target":"example.com","country":"US","language":"en"}`.
+SERP `ensure` collects at most one saved snapshot per returned keyword and Keyword Research report. Repeat calls reuse the saved job, including failures. SERP show/wait/export only read; market and device come from the parent report.
+
 Reading/planning/saving spends no research credits. Launch uses Organization credits and the same
 server admission as the interface. Keep the retry key after an uncertain response; no paid retries
 are automatic. Wait exit 3 means pending; exit 4 failed/cancelled. Partial evidence remains readable.
@@ -241,33 +252,27 @@ version 1 and does not include credentials. The focused plugin skill is `siteos-
 siteos health-check --json
 ```
 
-Diagnostics report local Project selection and legacy service references without contacting APIs
-or reading runtime credentials. A selected Project means local setup exists, not remote health.
+Diagnostics report the common Project selection and local Pulse configuration without contacting
+APIs or reading runtime credentials. A selected Project means local setup exists, not remote health.
 Set `SITEOS_HOME` to relocate private CLI state. Never commit `auth.json` or private bindings.
 
-Legacy `pulse project`, `forms project` and `search project` selections remain supported for existing
-repositories. Their service-aware bindings and tracked references (`siteos.config.json`,
-`.siteos/forms/project.json`, `.siteos/search/project.json`) are fallback context when no common
-Project is selected. They do not create common attachments. Old global `.siteos/project.json` and
-old shared API keys are not imported or interpreted.
-
-The retained Pulse migration can import a matching version 2 private binding from
-`${XDG_CONFIG_HOME:-~/.config}/siteos/pulse/project-bindings.json` only when the origin, repository,
-Organization and tracked Pulse slug agree. It leaves the original file untouched.
+CLI 2 uses only `siteos project` for Project selection, service setup and environments. Service-local
+Project and environment commands and binding imports have been removed. Re-select existing Projects
+with `project use`; this preserves their data, attachments and credentials. Module resource IDs are
+internal references, not common Project IDs or browser URLs.
 
 ## Origins and errors
 
 `SITEOS_AUTH_BASE_URL` selects the shared application origin for common Projects and all service
-commands using that context (default `https://app.siteos.sh`). The legacy service flows retain
-`SITEOS_PULSE_API_URL`, `SITEOS_FORMS_PUBLIC_URL` and `SITEOS_SEARCH_PUBLIC_URL` overrides. Runtime
+commands using that context (default `https://app.siteos.sh`). Runtime
 integration uses its service's configured public URL and scoped credential.
 
 Run `siteos <group> --help` for supported commands. Exit code 0 means success, 2 invalid usage,
-and 1 an operational failure. Legacy Pulse additionally uses 3, 4 and 5 for authorization,
+and 1 an operational failure. Pulse additionally uses 3, 4 and 5 for authorization,
 conflict and unavailable-service failures. JSON output is intended for agents and automation.
 
 One SiteOS plugin supports Codex and Claude Code, with a general workflow and focused service
-skills. Common Projects require CLI 1.1.0 and plugin 1.3.0 or newer.
+skills. The current common-only workflow requires CLI 2.0.0 and plugin 2.0.0.
 
 ## Development and publication checks