SiteOS CLI

@siteoshq/cli exposes one siteos binary for Auth, common Projects, Pulse, Cookie, Forms, Search, Trace, SEO/GEO, Analytics, Storage and Integrations. Use siteos --version to check the installed version; 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.

License

The @siteoshq/cli package is licensed under the MIT License. Copyright (c) 2026 Pixel Point.

Install and authenticate

npm install --global @siteoshq/cli
siteos --version
siteos auth start --email [email protected] --json
siteos auth complete --token '<one-time-token>' --json
siteos auth organizations --json
siteos auth select --organization '<organization-id>' --json
siteos auth status --json

If a newly released command is missing, check the resolved executable with command -v siteos (or Get-Command siteos in PowerShell) and siteos --version. Use npx --yes @siteoshq/cli@latest --version and the same invocation for the needed command to avoid an older local/global binary. Keep the repository, origin and SITEOS_HOME unchanged. For npm cache permission errors, use --cache <new-user-owned-temporary-directory>; a file workflow does not require changing ownership of a shared cache.

The one-time token is secret. Only auth complete receives it. The durable session is stored privately in ~/.siteos/auth.json. Product commands exchange it for short-lived, audience-bound grants; the durable session never reaches a product endpoint.

Current Organization permissions

siteos auth access --organization <organization-id> --json describes the current membership's service actions and the supported CLI and MCP subsets. It requires a server with service access enabled. The command neither changes the selected Organization/Project nor issues a product grant. Storage catalog capabilities describe the current request. CLI folder reads use catalog-only grants, so false upload/publication flags do not mean the user lacks those permissions. Newer servers report capabilitiesBasis: current_request and separate server availability. Use the access command above for the user's CLI actions; server availability is not authority.

Every operation still checks current membership and the grant's original ceiling, audience and scopes. A denied service cannot be accessed by selecting a different interface or requesting broader scopes.

Hosted origins

CLI 1.2.0 defaults to https://app.siteos.sh for Auth and every service. Existing credentials and repository bindings retain their selected origin; sign in again when moving installations. Never copy private state between production and staging.

For the separate SiteOS staging installation, set all four overrides before authentication:

export SITEOS_AUTH_BASE_URL=https://siteosapp.xui.se
export SITEOS_PULSE_API_URL=https://siteosapp.xui.se
export SITEOS_FORMS_PUBLIC_URL=https://siteosapp.xui.se
export SITEOS_SEARCH_PUBLIC_URL=https://siteosapp.xui.se

These select the SiteOS installation. A Project's Production or Staging Environment is a separate, project-level selection inside that installation.

Select one Project

From the website repository:

siteos project list --json
siteos project create --name "Storefront" --slug storefront --url https://example.com --json
siteos project use storefront --organization <organization-id> --environment production --json
siteos project status --json
siteos project connect forms --json
siteos project connect search --json
siteos project environment create --name Staging --slug staging --url https://staging.example.com --json
siteos project environment use staging --json

Creating a common Project records its catalog and a Production Environment. It does not create service resources. Each explicit connect creates the requested resource and, where supported, the selected common environment atomically. Cookie and Trace setup remains unpublished; Pulse monitoring remains disabled until configured. Use --resource '<service-resource-id>' to adopt an existing resource. No name, slug or URL matching is used for adoption.

Existing resource environments also require explicit adoption:

siteos project environment resources forms --json
siteos project environment connect forms --environment production --resource '<forms-environment-id>' --json

Omit --resource to create a new local environment. siteos project environment list reports the common catalog and connections. Forms/Search/Trace operational --environment flags accept common slugs and resolve explicit native bindings; without the flag, commands use the selected environment. Pulse/Cookie/SEO use separate bound resources per environment. Missing bindings fail without a fallback. Manage names and website URLs with project update and project environment update <slug>. 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/projects.json. It does not write a tracked global Project file. All service management commands request grants for the bound Organization, independently of the global Auth default. Use project list|create|use --organization <id> for an explicit Organization without changing that default. Selecting a new Project requires --environment; reselecting the same Project retains its environment. project status --json reports the effective safe context. The same bound context is used for project connect and project update, including their readback. Neither command requires changing the global Auth Organization. An access denial never falls back to another Organization.

Service workflows

Pulse

siteos project connect pulse --json
siteos project status --json
siteos pulse init
siteos pulse validate --json
siteos pulse test
siteos pulse deploy --dry-run --json

Initialization uses the common Project identity and selected environment URL. Deployments resolve the bound Pulse resource and current URL; local tests use this URL unless explicitly overridden. siteos.config.json remains the tracked Playwright check configuration. Deployment and enabling monitoring are explicit operations. deploy --dry-run builds locally without uploading.

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. 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 values in Pulse Settings for the selected Environment. The runner exposes declared values through process.env.NAME; pulse sync --check --json suggests names found in imported source, while computed names need explicit declarations. PLAYWRIGHT_BASE_URL remains a system value. Use the CLI build containing this support together with the matching application/runner release; earlier published versions do not preserve these declarations. See Pulse variables operations for storage and diagnostics.

Forms and Search

siteos project environment list --json
siteos forms definition check --source siteos.forms.ts --json
siteos forms deploy --source siteos.forms.ts --json
siteos forms credential issue --environment production --install --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

Credential installation writes only the owned assignments to a safely ignored .env and never prints values. Forms submission credentials and Search query/indexing credentials remain separate and environment-scoped. forms submit --input '<path>' uses only its runtime credential; it does not acquire management authority. Definition checks remain local.

Cookie, Trace and Integrations

siteos project connect cookie --json
siteos cookie status --json
siteos cookie installation --json
siteos cookie draft get --json
siteos project connect trace --json
siteos trace environments --json
siteos trace installation show --environment production --json
siteos trace report --environment production --json
siteos trace destinations --environment production --json
siteos trace events --environment production --provider ga4 --period 7d --json
siteos trace issues --environment production --state active --json
siteos trace observations --environment production --provider ga4 --event purchase --json
siteos integrations status --json
siteos integrations connect --json

CLI 2.39.0 accepts every Trace service family in --provider (including zoominfo, linkedin and clarity), vendor:<id> for a vendor-registry service (for example vendor:hotjar) and domain:<registrable domain> for a service the registry does not recognize.

Cookie/Trace draft editing and publication are separate commands with separate authorization scopes. Save commands take versioned JSON input; inspect --help and the focused plugin skill.

Trace explorer commands require CLI 1.8.0 and the corresponding Trace server release. They return one page with items, total, nextCursor, from and to. Repeat the same filters with --cursor <nextCursor> to continue; omit the cursor to refresh the window. trace issue show --id <uuid> reads finding history, and trace observation show --batch-id <uuid> --event-id <uuid> reads a specific observation. These commands use read authority and the explicit Project environment binding. custom means the data layer source, not a confirmed destination.

trace issue acknowledge|resolve --id <id> and trace issue snooze --id <id> --until <ISO date|24h|7d> act on an issue only after reading it in the selected environment, using Trace write authority. trace campaign-tagging [--period 24h|7d] reads landing campaign names. Observations include personalData (kind, location and name, never a value) and campaignParameters. trace installation publish refuses with OUTDATED_RUNTIME when pages ran a runtime in the last 24 hours that cannot read the new configuration; --acknowledge-outdated-runtime publishes anyway.

After reviewing a tracking plan, use trace tracking-plan publish --expected-draft-version <number> to publish that version. A conflict must be reread and reviewed; do not retry without the version guard. Existing installation and report commands remain compatible. Deployment of the Trace server and runtime precedes announcing the new explorer commands in the public plugin. Installation commands return the service-owned snippet and actual publication state. A Trace snippet is unavailable until runtime publication succeeds. Integrations connections belong to the Organization; provider authorization opens the shared browser flow, and notification destinations are connected explicitly by each service.

GitHub and PR verification

CLI 2.28.0 requires a matching server. integrations github status --organization <id> --json reads the shared catalog. authorize returns a GitHub consent link; the user completes consent, then candidates lists verified installations and connect --installation <id> connects the chosen one. Installation alone does not connect SiteOS. refresh queues catalog discovery; read status until ready. disconnect --installation <id> --confirm affects all consumers.

For the selected Project/environment, project repository show reads the binding and project repository save --input <binding.json> saves with revision: null for a new binding or the current binding ID for an edit. Pulse must be explicitly attached and its Checks published. pulse pull-requests policy show reads settings; policy save --input <policy.json> accepts enabled, useRepositoryChecks, and checkIds. Execution time uses the organization’s monthly Pulse budget; there is no daily PR quota. Read-only repositoryCheckIds is not an input field. pull-requests list reads saved attempts with --cursor pagination. Repository bindings and PR policy do not modify schedules or publish tests. See the PR workflow for examples, preview requirements and independent Check participation.

SEO/GEO

The application calls this service SEO/GEO; its command and Project service key remain seo. GEO means generative engine optimization, including technical AI-search accessibility and AI mentions/citations. Check siteos seo --help against the installed CLI and server version.

Site Audit checks public HTML, canonical, robots.txt, sitemaps, snippets and basic structured data. Its crawler-policy checks do not prove access from actual provider IPs. Performance adds selected-page Lighthouse and response/rendered HTML comparisons. Brand lookup and Prompt checks provide separate AI visibility evidence. No autonomous agent journey or target API/MCP audit is performed by these commands, and no result guarantees AI inclusion or a universal AI rank.

siteos project connect seo --json
siteos seo status --environment production --json
siteos seo audit run --environment production --json
siteos seo audit run --url https://staging.example.com/new-page --environment staging --json
siteos seo audit list --json
siteos seo audit show '<audit-id>' --json
siteos seo pages --audit '<audit-id>' --json
siteos seo issues --audit '<audit-id>' --json
siteos seo changes --audit '<audit-id>' --state resolved --json
siteos seo repair --audit '<audit-id>' --url https://example.com/pricing --rule metadata.description_missing --json
siteos seo recheck --audit '<audit-id>' --url https://example.com/pricing --url https://example.com/about --json

Setup performs no crawl. audit run queues a full HTML audit; recheck queues 1–20 explicitly selected, previously observed URLs. CLI 2.1.0 adds repair and repeated recheck --url values. The optional --resource guard rejects a different Project environment before sending the request. Repair briefs read saved evidence without an AI call; they do not authorize a deployment or another audit. Full HTML audits allow 1–500 pages (default 100); the selected server and saved settings enforce that limit independently of the installed CLI version. Read the returned audit ID until a terminal state; a queued response is not a result. audit cancel '<audit-id>' revokes further work. Pages and changes are paginated with --page.

issue ignore and issue restore require --audit, --url, --rule, --reason and the current --revision (0 before the first decision). They use a distinct issue-write scope. Read back the decision after success; a revision conflict requires refreshing it. Ignore never means resolved. Independent AI content checks are available for enabled Project environments through CLI 2.16.0:

siteos seo content status --environment production --json
siteos seo content findings --scan '<scan-id>' --status confirmed --page 1 --json
siteos seo content history --json
siteos seo content run --environment production --json
siteos seo content continue '<scan-id>' --environment production --json
siteos seo content cancel '<scan-id>' --environment production --json

Reads never start provider work. Follow nextPage with the same resultsScan.id and filters; history contains the latest 20 retained scans. Paid run/continue/cancel require an owner/admin and seo:research:run; ordinary technical-audit authority does not grant this permission. Unconfirmed signals are separate from confirmed suggestions, which still need review before editing a website. Findings whose saved text a later page fetch no longer found are outdated: other reads leave them out and report their outdated count, and findings --status outdated lists them. Outdated does not prove the page is now correct. Credit renewal never resumes an old scan automatically. Disabled checks remain unavailable; a CLI upgrade alone does not enable them.

All SEO/GEO commands resolve the selected common Project and explicit environment binding. seo audit run --url <url> checks 1–20 explicit URLs, including pages absent from earlier audits. Repeat --url for multiple pages. Every URL must use the selected environment's exact website origin; fragments are removed and duplicate URLs are checked once. The matching server must support page-audits. No links are followed and the full-site summary is preserved. The optional --audit <baseline-id> selects a compatible, terminal, unexpired baseline and requires --url; otherwise no previous audit is needed. --resource <expected-id> guards the environment binding. Without --url, audit run starts the usual full audit. seo recheck continues to require URLs observed in its source audit. Read the returned ID with seo audit show until terminal, then inspect seo pages --audit <id> --url <url>. Queue acceptance does not mean the page passed. For pre-production review, select the environment configured with that public staging origin. Localhost, private networks, password-protected sites and arbitrary preview origins are unsupported; robots.txt, path exclusions and the normal crawl protections still apply.

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
siteos seo research retry <run-id> --idempotency-key <continuation-key> --json
siteos seo research export <run-id> --format json --output ./research-report.json --json
siteos seo gsc status --json
siteos seo gsc report --dataset queries --filter all --json
siteos seo opportunities --type close-to-top --limit 5 --json
siteos seo gsc export --dataset queries --format csv --output ./gsc-queries.csv --json

Run siteos seo --help for request JSON, limits, saved inputs, cancellation and GSC settings. CLI 2.41.0: seo opportunities [--type ...] [--status open|hidden] [--limit 1-100] reads the ranked Opportunities list built from saved Google Search, Site Audit and AI Visibility evidence. It never syncs Google, runs research or spends credits. Research supports keywords, Domain Overview (domain), rankings, backlinks, brand and AI visibility without GSC. AI Visibility category history uses --kind ai-rankings; Prompt checks stays separate under --kind ai-visibility. Category requests use kind: ai-visibility with a category-mentions-v3 category: ordinary answers, text Mentions and Citations. Historical reports retain AEO scores and annotations. Reports and exports include model settings and the exact supporting answers. See the SEO skill's AI visibility reference for the versioned request and scoring method; historical v1 reports remain readable without inferred scores. 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. Exports retain scope/coverage and refuse overwrite. Research CSV includes JSON cells for request, dataset metadata and rows; JSON is preferable for programmatic analysis.

GSC uses saved comparisons and an explicitly connected property. Reports page by 25; exports include all matching normalized rows, up to the 20,000-row current/previous union bound. gsc sync queues the Google worker without research credits. Google OAuth remains interactive; gsc bind/disconnect manage only this environment with revision checks. Separate grants control research read/run/write and GSC read/sync/write. Audit authority alone never enables paid research. These source capabilities require coordinated CLI/server/plugin publication; they are not a claim about the current npm version.

Auth policy permits CLI service-grant issuance to Organization owners/admins. JSON uses contract version 1 and does not include credentials. The focused plugin skill is siteos-seo.

Local state and diagnostics

siteos health-check --json

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.

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). 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. 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. The current common-only workflow requires CLI 2.0.0 and plugin 2.0.0.

Development and publication checks

From this workspace:

pnpm --dir packages/cli format:check
pnpm --dir packages/cli typecheck
pnpm --dir packages/cli test
pnpm --dir packages/cli build
pnpm --dir packages/cli pack:check

pack:check creates the publishable tarball locally. It does not publish the package.

Cookie verification

Before Cookie setup or publication, cookie terms show --json returns the full current agreement, its digest and the selected Organization's acceptance. After the owner or admin reviews those exact documents and explicitly authorizes electronic acceptance, use:

siteos cookie terms accept --version REVIEWED_VERSION --document-digest REVIEWED_SHA256 \
  --confirm --json

No typed-name or company fields are required. Confirm authority for the displayed Organization and read the status again; cookie terms history --json and cookie terms receipt --version REVIEWED_VERSION --json provide the stored records. Setup and publication requests alone do not authorize contract acceptance. The CLI and application must both support version and document-digest checks. Use the server-returned version and documents, including the platform DPA in the same explicit acceptance. Historical Terms-only acceptance is not acceptance of that DPA.

CLI 1.2.0 adds cookie schema, cookie validate --input draft.json, cookie regions resolve --country GB --source published and cookie restore --input restore.json. Restore changes the draft only. Validation makes no write and reports a stale draft version.

From the selected website repository, run siteos cookie verify --json or siteos cookie verify --url /pricing --browser webkit --json. Install the matching local browser when requested with npx [email protected] install chromium or npx [email protected] install webkit. The check opens fresh contexts, exercises the public consent API and reports request origins and storage names without values, query strings, request bodies or authenticated sessions. These are real visits; normal installation/aggregate signals may be recorded. Reports remain local. CLI 2.3.1 distinguishes the /gtm.js container bootstrap from /gtag/js and recognizes regional GA4 /g/collect endpoints. Loading GTM to run the consent manager is not itself evidence that an Analytics tag ran; a GA4 request after withdrawal remains a failure in Basic mode. The verifier recognizes siteos_consent_<publicKey> only for the current banner when the published configuration enables shared subdomain consent. Other banner keys remain unclassified; matching vendor storage is still checked against consent. The legacy siteos_consent cookie remains recognized.

A report records the revision, runtime, observed Edge location, scenario scope and 24-hour expiry. Runtime 11.7 adds reasoned service permissions and refusal retention across policy/region changes; these are browser capabilities, not new CLI commands. The verifier remains compatible with its existing getDebugState().services[].allowed contract. It does not simulate policy transitions or verify grant-event deduplication; check those separately before claiming that scope passed. passed exits 0; needs-review and failed exit 1. Unknown origins/storage require classification. The check covers one route and a bounded observation window, not hidden first-party/server-side tracking, every delayed interaction, visual accessibility or legal compliance. Repeat after website/publication changes and preserve a separate GTM Tag Assistant check where applicable. --url stays within the selected Project environment's origin. Verify shared choices and withdrawals between authorized subdomains, and click any custom footer privacy links, in a separate fresh-browser journey; see the Cookie skill's domains and privacy links guide.

Forms inbox

Use siteos forms submissions list --environment <slug> --form <form-id> --json to search complete history. Filters include --query, --status, --from, --to, --limit (1–100), and --cursor. The response contains the filtered total and a continuation cursor. Full answers and the saved version's labels are available with siteos forms submissions read --environment <slug> --form <form-id> --submission <id> --json.

siteos forms submissions status --environment <slug> --form <form-id> --submission <id> --status read --expected-status new --json changes status without overwriting concurrent triage. Statuses are new, read, archived, and spam. These management commands require the matching Forms inbox server release. They use the selected common Project/environment and a scoped Auth grant. forms definition check compiles the schema locally using the same strict Ajv policy as sync.

Form archive and deletion

These commands require the lifecycle API on the selected server. Owner/admin rights are required for changes; members can list and read. Read a form to obtain its current revision before changing it.

siteos forms definition list --environment production --status all --json
siteos forms definition read --environment production --form <form-id> --json
siteos forms definition archive --environment production --form <form-id> --expected-revision <revision> --json
siteos forms definition restore --environment production --form <form-id> --expected-revision <revision> --json
siteos forms definition delete --environment production --form <form-id> --json
siteos forms definition delete --environment production --form <form-id> --apply --confirm <form-key> --expected-revision <revision> --expected-submissions <count> --json

Delete without --apply only previews the exact Project, Environment, form and submitted-answer count. Use the values from that reviewed preview when applying; a stale revision or count conflicts. Archive stops new submissions and preserves history. Delete permanently removes versions and answers from the working database, retaining only a reserved-key tombstone. That form key cannot be reused. Shared Environment credentials remain active for other forms. Sync refuses archived/deleted keys and never removes forms missing from a local manifest. Backups follow deployment retention; they are not an in-app restore mechanism.

Forms publication from existing Zod schemas

CLI 2.45.0+ reads an ordinary server-only siteos.forms.ts module exporting an array of @siteoshq/forms contracts. Each contract references the project's existing Zod schema plus inbox metadata. Keep the original schemas, resolvers and types; the package owns portable conversion and version fingerprints. No generated project JSON, copied converter or website build hook is required.

--source evaluates trusted local JS/TS in a bounded child process. It is not a sandbox. Arbitrary source logs are suppressed and the child does not inherit CLI credentials. Keep configuration imports side-effect free.

Install a publication key with siteos forms deployment-key issue --environment production --install --json. It belongs in ignored local .env, or optionally a trusted CI secret store for unattended publication. Explicitly load it into the publication process alongside SITEOS_FORMS_PUBLIC_URL. The agent checks, publishes and reads back the complete inventory as part of an authorized form change:

siteos forms definition check --source siteos.forms.ts --json
siteos forms deploy --source siteos.forms.ts --json

Publish before routing traffic to the new server contract. Deployment uses the Environment-scoped key without interactive Auth state and is atomic. The website server sends the package contract's contractVersion with each parsed payload. Ordinary builds do not publish. forms deployment-key list|revoke manages publication keys; submission keys cannot publish. Existing --manifest workflows remain supported until deliberately migrated. See the Forms skill for setup and readback.

Runtime uses only SITEOS_FORMS_PUBLIC_URL and the submit-only SITEOS_FORMS_API_KEY. CLI 2.44.0+ installs that canonical key name and accepts the previous SITEOS_FORMS_SUBMISSION_CREDENTIAL as a fallback. If both non-empty values are set, the canonical value wins. Include an optional SITEOS_FORMS_DEPLOYMENT_KEY placeholder in .env.example, labeled for local publication or trusted CI only. Developers can edit, typecheck and build without it; do not add it to hosted application runtime.

Website Analytics

The source CLI includes siteos analytics for an explicitly connected Project environment. Check siteos analytics --help against the installed package and server before use; source availability does not establish publication. Start with project status, analytics status and analytics installation. Use --environment <slug> when selecting the target explicitly.

analytics settings show returns the current revision. analytics settings set --revision <n> accepts partial --enabled true|false, --cookie-events true|false and --minimal-realtime true|false updates. Analytics collects independently by default. Native consent control belongs to Cookie's published integrations.siteosAnalytics switch in the same Project environment; attachment or a draft save does not enable it. External CMP gating is optional and must be configured before runtime initialization. Privacy signals and full opt-out still apply. Reload the website after configuration changes.

Layered measurement (2.17.0 candidate)

analytics measurement show|review reads and reviews the owner's cookieless, browser recognition and optional customer-provided identity policy. measurement prepare --file saves a plan without activating collection; measurement activate --file requires the returned revision and reviewed plan. Browser recognition and history have separate lifetimes. Consent, installed-runtime capability and accepted-event evidence remain separate from the configured mode. Cookie disclosure preparation saves a draft only; publication and the visitor's explicit permission are independent steps. Customer identity requires the website's own backend assertion, never an email inferred from a page visit or banner grant. See the canonical Analytics skill for exact commands, signing-key and People access scopes. Publish the matching server before distributing this CLI candidate.

analytics events list|create|snippet manages registered definitions with categorical Lists or explicit { "type": "public_text" } values (public content, 1–256 Unicode code points, never visitor input or personal data). events widen --file <reviewed-change.json> changes one existing List to Text under its current definition revision; review the catalog from events list first. Its file contains operation: "widen_property", name, property, and revision. Conflicts require a fresh review; never guess the next revision. Upgrade the server/Edge/runtime before enabling Text. Delete a custom event with events delete <name> --revision <reviewed-revision> --confirm <name>. For one property, add --property <key> and confirm the property key instead. This stops future collection while preserving retained statistics and reserving the old name; it cannot be undone. Read events list first, which includes deletion metadata. A conflict requires another review. Snippets exclude deleted properties and cannot be generated for deleted events. analytics campaigns list --status active|archived|all defaults to active campaigns. Use campaigns archive <id> or campaigns restore <id> to organize the selected environment's catalog. Archived campaigns retain their statistics and continue attributing visits from shared links; archiving does not pause collection or free a registered-campaign slot. Read with --status all before creating a campaign to find any archived entry with the same UTM values. Creation uses --file <definition.json>; campaigns, goals, funnels, reports and realtime keep their existing contracts. Exact Text values can be used in property filters and conversion conditions. analytics monitoring prepare prepares a Trace draft without publishing it. Auth grants are scoped to Analytics and the operation, with editor roles required for writes. Analytics is Unlimited in Usage during early access. See the canonical plugin's website Analytics skill for event contracts and the browser-to-report verification workflow; Search reports use search analytics separately.

Trace actionable monitoring (2.2.0)

trace coverage, trace gtm summary, trace notifications show and trace notifications destinations read the selected environment. trace observations list accepts --kind tag_execution, --container-id, --tag-id and --result; trace issues list accepts the same GTM identity filters. trace notifications save|retry --input <file> and trace schema-baselines reset --input <file> are explicit, version-guarded writes. See the Trace workflow for exact inputs, thresholds and installation of the common GTM execution monitor. The installation response supplies gtmExecutionMonitor.templateUrl and its trigger contract. MCP exposes read-only issue, event, observation, coverage, GTM and notification views.

CLI 2.40.0: trace services [--period 24h|7d] reads the service map: each service's mapped GTM tags, real traffic and consent, Cookie scan items and Cookie banner status, with their own sources and dates (MCP siteos_trace_get_services). Cookie columns are null without Cookie read access. Rows carry identity (how Trace knows the service), kind (unidentified_tag for a GTM tag that loads only hosting or CDN files), paused, state, action and cookieReference; the map lists hosting and CDN domains from traffic under infrastructure. The server adds these fields; the CLI prints the same JSON.

Search content and quality

Each common Project environment can hold independent Search indices. List them with siteos search index list --environment production --json, or create one with siteos search index create --environment production --name "Blog" --slug blog --json. Use the returned ID as --index <id> on hosted Search commands. Content, suggestions, relevance, crawlers, visitor reports and credentials stay scoped to that index. Omitting --index retains the legacy Default index; an unknown explicit ID never falls back.

CLI 2.46.0+ installs a credential with --index <id> --install using conventional SITEOS_SEARCH_* names for a new single search. For another search, add --env-prefix SITEOS_SEARCH_BLOG (or SITEOS_SEARCH_DOCS) to credential issue/rotate. A prefix already occupied by another index or unbound credentials fails before issuance. Repeated installs retain their index/prefix binding; older ID-derived installations also keep their names. The ignored .env holds a non-secret binding comment; preserve it. No credential is printed or copied to hosting by installation. Use the returned installed.envPrefix and variable names in the corresponding website route, hosting environment and index: { id, envPrefix } content-sync configuration. The offline search migrate algolia converter has no server target; select the destination when importing. MCP reads accept indexId; index creation and other writes use CLI or the application.

siteos search crawl list --environment <slug> lists crawlers. Create one with crawl create --name "Documentation" --file <crawler.json> or update it with crawl configure --crawler <id> --file <crawler.json>. Use --environment <slug> for every command. Configuration includes HTML scope and a schedule with selected weekdays, time and time zone. Use crawl start --crawler <id>, read crawl status --crawler <id>, then crawl publish --run <id> --apply after reviewing changes. Partial crawls additionally require --accept-truncated. The crawler preserves other sources and keeps the current index serving until publication. See the canonical Search skill crawler reference for limits and robots/noindex policy.

siteos search sync --environment <slug> --file <payload.json> validates and previews a full replacement. Add --apply after reviewing removals. search content inspects the published documents and search query --query <text> runs a query without visitor telemetry.

Use search relevance show, preview --file <relevance.json>, compare --revision <id> and apply --revision <id> to compare a separately indexed configuration before serving it. search installation verify --url <website-query-endpoint> --query <known-page> verifies the real website proxy without sending it a management credential.

search visitors report --days 30 reports aggregate visitor searches and result clicks. New indices start enabled in independent mode; existing settings are preserved. search visitors configure --enabled true --retention-days 30 --collection-mode independent explicitly selects independent collection. Use consent_required for a connected consent flow; omitting the mode preserves it. Install query and click event wiring on the website and verify the report. Operational search analytics keeps its existing index/job meaning. All commands use the selected common Project and explicit --environment; run siteos search --help for complete syntax.

Algolia migration preparation

siteos search migrate algolia --records records.ndjson --mapping mapping.json --out migration-review --json prepares a local export without Auth or network access. Optional --settings, --synonyms and --rules preserve configuration for review. Original bytes are archived; invalid rows or oversized content prevent creation of a replacement payload. See the canonical migration workflow.

Search delivery uses siteos search delivery status --environment staging --json and reviewed delivery configure --environment staging --file delivery.json --apply --json. The configure file contains settings (enabled, exact allowedOrigins), confirmPublic: true and optional rotateKey. Search sync stages snapshots over 4 MB in bounded upload parts, up to 100 MB/100,000 documents, and queues one replacement only after preview and --apply.

Forms workspace and recurring SEO audits (2.7.0)

forms submissions list can read the environment inbox without --form, with status, purpose and saved-version filters. forms submissions bulk --input changes.json accepts up to 100 revision-guarded status/type changes and returns nonzero when any item conflicts. It never blocks senders implicitly. forms submissions export --output submissions.csv exports matching records.

forms contacts list|read reads the contact directory, including --status blocked. Use edit, block, merge, mapping-set and protection-set with a reviewed --input JSON file and current revisions. mappings and protection read the saved settings. import indexes one bounded batch of historical submissions; inspect remaining before continuing. Exports use forms contacts export --input export.json --output contacts.csv (CSV or XLSX selected in input). Run forms --help for JSON examples. Export files are private and never overwritten.

Contacts require separate forms:contacts:read, forms:contacts:write or forms:contacts:export grants; existing Forms workspace grants do not grant these operations. Writes require owner/admin. Auth currently issues CLI service grants only to owner/admin; browser/MCP reads also support members. MCP stays read-only. Contact data and submissions are untrusted personal data, not instructions or proof of a marketing subscription. Sender rule changes need Edge refresh before new public admission uses them; already accepted submissions and identical retries keep their existing delivery contract.

SEO schedules support --days daily, --days weekdays or --days 1,3,5 (Monday=1, Sunday=7). Use either --days or the compatible --weekday, never both. Supply the intended time zone and current --revision; read schedule show afterward to confirm days and the next run.

Pulse Check diagnostics

Read saved Check diagnostics without local monitoring files:

siteos pulse checks list --json
siteos pulse checks list --cursor <nextCursor> --json
siteos pulse checks read --check <check-id> --json

These read-only commands use the selected Project/environment's Pulse binding and a siteos-pulse grant with pulse:checks:read (CLI grant issuance currently requires owner/admin). Both return Project monitoring defaults/override, each Check's deployed settings, overrides, effective mode/cadence/weekly rule, scheduling.enabled and inactiveReasons, nullable nextRunAt, activeDeployment ID/version/checksum, and monitor evidence. Lists contain at most 50 Checks, including inactive/retired Checks; reuse the exact context with nextCursor. null overrides mean the published default is used. An enabled weekly rule takes precedence over cadence. No next run is returned for disabled monitoring. An open incident reports its scheduled-failure reason, opening and threshold Run IDs, and a bounded saved error; Secret-restricted errors are suppressed. A manual Check may retain an old open incident: publication, schedule changes and manual passes do not resolve it. These commands require the matching application read endpoints; inspect pulse --help and server availability when using an older installed release.

Remote Pulse verification (2.13.0)

After an authorized Check deployment, run one exact Check in the selected environment:

siteos pulse run --check <check-id> --json

Use the Check ID returned by deployment or saved run evidence. This requires the matching server and a pulse:runs:write service grant; it does not deploy local changes. The response provides the Run ID, request ID and target context. Read the terminal result with siteos_pulse_get_run; a queued response is not a successful Check. If admission is uncertain, reconcile existing runs and retry the same request with --request-id <original-id>. Do not retry through browser clicks. A manual pass does not resolve scheduled monitoring incidents.

Pulse Check usage in configuration v3

Use matching CLI and server builds for configuration version 3 (local implementation until the coordinated release). Existing v1/v2 files keep their monitoring behavior. Each v3 Check explicitly sets its schedule and may opt into PR verification with pullRequests.enabled:

{
  "version": 3,
  "project": {
    "slug": "website",
    "name": "Website",
    "monitoringEnabled": true
  },
  "testsDir": "tests/siteos",
  "checks": [
    {
      "slug": "smoke",
      "name": "Smoke",
      "include": ["tests/siteos/smoke.spec.ts"],
      "active": true,
      "schedule": { "mode": "scheduled", "cadenceSeconds": 300 },
      "pullRequests": { "enabled": true }
    },
    {
      "slug": "checkout",
      "name": "Preview checkout",
      "include": ["tests/siteos/checkout.spec.ts"],
      "active": true,
      "schedule": { "mode": "manual" },
      "pullRequests": { "enabled": true }
    },
    {
      "slug": "crm",
      "name": "CRM delivery",
      "include": ["tests/siteos/crm.spec.ts"],
      "active": true,
      "schedule": { "mode": "scheduled", "cadenceSeconds": 3600 },
      "pullRequests": { "enabled": false }
    }
  ]
}

manual means no schedule; it does not prevent selected PR runs. active: false disables a Check for both uses. PR Checks cannot require environment variables/Secrets and must use the preview base URL. pulse sync preserves this intent and does not opt newly discovered Checks into PRs. pulse deploy --dry-run --json includes the v3 manifest and all Check usage declarations.

The environment PR policy either follows the repository configuration or preserves a custom selection. Deployment changes repository defaults, never overwrites that custom selection, and never enables automatic PR verification. Configure the repository/preview and enable automatic verification separately in SiteOS. Read pullRequests via pulse checks list/read or the matching MCP Check readers to reconcile defaults, selection source, eligibility, and blocked reasons.

Storage

Store private Project files and publish selected immutable versions for a website. Select the repository's exact Organization, Project and environment first; Storage never falls back to Production.

siteos project use '<project-id-or-slug>' --organization '<organization-id>' --environment production --json
siteos storage status --json
siteos storage list --json
siteos storage folders list --json
siteos storage folders create --name Assets --json
siteos storage list --folder '<folder-id>' --json
siteos storage inspect '<file-id>' --json
siteos storage --help

If the environment has no library yet, siteos project connect storage --json explicitly creates it. Storage uses separate siteos-storage grants under canonical Auth policy. MCP catalog reads do not issue CLI write authority. Upload receipts and pending publication are not readiness or backup proof. Use stable IDs/revisions, retain one upload intent, and download to a new file. See the help for resume/replace, publication media types and safe retry behavior. Availability requires matching application and CLI releases; source changes do not publish an npm version. Upload up to 100 local files in one command. Preview names before choosing a conflict policy:

siteos storage upload ./hero.png ./cover.png --dry-run --json
siteos storage upload ./hero.png ./cover.png --on-conflict skip --json
siteos storage upload ./hero.png ./cover.png --on-conflict replace --json

The default returns UPLOAD_CONFLICT (exit 4) with counts and the plan before transferring any files. skip keeps existing files; replace saves new versions using the inspected revisions. Both skip duplicate names in the input and names already uploading. Matching is case-insensitive within the destination folder, after Unicode normalization and trimming. Earlier versions and published URLs are preserved. Revision conflicts never silently retry against newer state.

Batches run sequentially and stop on failure or unresolved processing, returning each file's receipt and the files not started. Inspect upload-status and resume the interrupted file instead of repeating an entire batch. --name, --replace, --resume and --idempotency-key are single-file options. Explicit replacement/resume/idempotency intents bypass name planning and cannot be mixed with --on-conflict or --dry-run. For a nested replacement, retain its folder and canonical name.

Use the folder ID from folders create or folders list with --folder when uploading. Inspect pending uploads and resume the same intent with its original local file:

siteos storage upload ./hero.png --folder '<folder-id>' --json
siteos storage upload-status '<upload-id>' --json
siteos storage upload ./hero.png --resume '<upload-id>' --json
siteos storage versions '<file-id>' --json
siteos storage download '<file-id>' --version '<version-id>' --output ./downloaded-hero.png --json

Downloads verify SHA-256 and refuse to overwrite a local file. A private upload becomes a public website asset only after explicit publication; the returned URL keeps pointing to that immutable version even when a newer version is uploaded. A shared link expires independently:

siteos storage publish '<file-id>' --version '<version-id>' --media-type image/png --json
siteos storage share '<file-id>' --version '<version-id>' --expires-in 3600 --json
siteos storage deliveries --json
siteos storage revoke '<delivery-id>' --revision '<current-revision>' --json

Replace <current-revision> with the actual revision from the relevant inspection or listing. Publication may be pending until acknowledged by Edge. Shared-link secrets are returned once; keep them private. Revoking a link stops future authorized delivery; it cannot recall downloaded bytes.

Catalog changes also require the current file or folder revision:

siteos storage rename '<file-id>' --name hero-final.png --revision '<current-revision>' --json
siteos storage rename '<file-id>' --name hero-final.png --folder '<folder-id>' --revision '<current-revision>' --json
siteos storage trash '<file-id>' --revision '<current-revision>' --json
siteos storage list --trash --json
siteos storage restore '<file-id>' --revision '<current-revision>' --json
siteos storage folders delete '<folder-id>' --revision '<current-revision>' --json

Read back after each change and use its returned revision for the next operation. Trashing retains versions and revokes their links; restoration does not republish them. Folder deletion requires an empty folder. These commands do not permanently purge file bytes or erase backups.

Optimize and convert images

Discover deployed availability with siteos storage images list --json. Image jobs require content-read and upload-write grants for the exact Project environment. MCP remains metadata-only.

siteos storage images create '<file-id>' --format webp --quality 80 --max-width 1600 --json
siteos storage images create '<file-id>' '<another-file-id>' --format png --json
siteos storage images list --json
siteos storage images inspect '<job-id>' --json
siteos storage images preview '<job-id>' --json
siteos storage images save '<job-id>' --json
siteos storage images cancel '<job-id>' --json

Create queues up to 20 files sequentially and returns per-file receipts/errors with idempotency keys and the inspected source version/revision when available. It reads each current version and revision before admission; a concurrent edit is rejected. For a specific version use --version ID --revision N on one file. After an uncertain response, inspect recent jobs; retry one file with its original --idempotency-key, --version, --revision and settings rather than creating another job. processing means queued/running; processed means a private candidate is ready to compare; ready means explicitly saved. Queuing never publishes or changes the source.

Static PNG/JPEG/WebP inputs are limited to 20 MiB and 16 megapixels. Optional --max-height, --max-width, --quality and WebP --lossless control processing. PNG encoding is lossless; dimensions never enlarge an image. JPEG conversion of transparency requires --background '#ffffff' (or another hex color). JPEG and JPG are the same format. Source metadata is removed and EXIF orientation applied.

Candidates expire after one hour. Confirmed cancellation, rejection or expiry releases reserved organization capacity immediately; physical cleanup follows separately. Inspection reports actual dimensions and sizes, including larger results. preview returns a private 60-second capability: do not commit, log or publish it. save promotes those exact verified bytes as a new file. Use --as-version --format keep at creation only when changing the current version is intended; old versions remain and existing published URLs stay unchanged. Publish the saved file/version explicitly when the task calls for website access. This requires the dedicated image worker and operator enablement; source availability does not establish a deployed feature.

Analytics websites

analytics domains list reads exact origins, membership revision, readiness and delivery evidence. Anonymous collection on several websites needs no banner or visit linking. Related sites may reuse the existing Project banner, including Cookie's optional shared subdomain choice, or select another published banner with domains consent-review --file <json> and domains consent-set --file <json>. Use exact Cookie Project/environment/resource IDs and the returned publication, membership and activation fences; see the linked websites runbook. These commands do not publish Cookie or transfer visitor choices between banners. domains add <origin> --revision <n> first registers the selected Project environment address under its own Projects grant. domains linking --enabled true|false --revision <n> changes current-visit continuation. domains remove <origin> --revision <n> --confirm <origin> removes a secondary origin without deleting retained statistics. Review the current revision before changing it. No consent or identity is transferred; each website requires independently configured recognition and permission.

PR code Checks

CLI 2.30.0 also supports the fixed built-in secret scanner command ["gitleaks", "dir", "."] in a PR-only code Check. It skips dependency installation and reports file/line/rule without key values. Hosted execution scans the selected PR head directory offline. Local pulse test --check secrets scans committed Git HEAD, downloads the checksum-pinned scanner temporarily on macOS/Linux x64/arm64, and excludes untracked/unstaged files. Use the same validate/deploy and PR policy workflow. A matching server and executor are required; this scans the current source snapshot, not Git history or all classes of security issue.

Config v4 adds type: "code", command: ["pnpm", "test:unit"], optional workingDirectory and timeoutSeconds. Set schedule: { "mode": "manual" } and pullRequests: { "enabled": true }. Existing browser configs remain supported. Use pulse test --check <slug> for one local Check; validate, sync, deploy and PR policy commands are unchanged. Code runs from the exact PR head without a preview on an operator-enabled executor. It needs a pinned npm/pnpm manager and lockfile; network, lifecycle hooks and Secrets are unavailable to the Check. See the workflow.

siteos pulse usage --json reads the selected Organization’s Pulse estimate and technical limits. Preview costs do not deduct credits. PR list JSON includes saved per-Check usage receipts; missing measurements remain unknown. Test configuration and deployment commands are unchanged.

GitHub repository sharing uses integrations github authorize --organization <id> --json, user consent, github candidates, then github connect --installation <id> --repositories <id,id>. Repeat the Organization flag on each command. Selection is additive and limited to the current human/App intersection; github remove --installation <id> --repositories <id,id> --confirm removes only that Organization's access. github disconnect does not uninstall the App.

Code Check validation also preflights committed Git HEAD before publication. Internal relative symlinks are supported; unsafe/missing/cyclic links identify their path. Local command success does not prove hosted installation or execution. A non-Git directory reports source compatibility as unknown.

Bind shared Google Analytics data

After sharing the intended GA web stream in SiteOS Services, select its Project/environment and inspect siteos analytics ga4 status --json. Use siteos analytics ga4 bind --connection <id> --property <numeric-id> --stream <numeric-id> --revision <current-revision> --json to bind it. Use revision 0 only for an unconfigured binding. Consent and Organization resource sharing remain browser operations. This binds reports; it does not install a website tag or publish GTM.

Cloud cookie scans

CLI 2.36.0 and a compatible hosted application expose cookie scans list, run, inspect --id, cancel --id, and schedule --input. Use the selected Project/environment. A manager can run/cancel and save schedules through cookie:scans:manage; workspace viewers can read reports. Read cookie scans list --json first: available=false means a published banner or hosted executor is missing. Do not treat an accepted queue response as a completed scan.

For an authorized scan, use cookie scans run --idempotency-key <uuid> --json; retain that UUID if retrying an uncertain response. Read the returned ID with cookie scans inspect --id <id> --json until terminal. Review pages, incomplete scenarios, issues and unclassified observations separately. The browser exercises first visit, rejection, acceptance, withdrawal and GPC; synthetic visits may appear in analytics/consent records. Values and payloads are excluded. Unknown storage/origins need review and do not prove a consent violation. Partial evidence cannot establish recovery.

Scheduling is an explicit write. Build its JSON from the returned settings using expectedRevision and these fields: enabled, cadence (weekly/monthly), weekday (1–7), time (HH:mm), timeZone (IANA), priorityPaths, excludedPaths, maxPages (1–50). Monthly means the first day. Remove read-only revision, origin, nextRunAt, pausedReason. Preserve the inspected environment; never enable another site's schedule or enlarge its scope implicitly. Read back the saved settings. Notifications use configured Integrations destinations in the Scans UI; CLI has no destination-write command. A manual pass does not prove scheduled execution, delivery or legal compliance.

Cookie inventory

CLI 2.38.0 and a compatible hosted application expose cookie inventory list, review --input and apply --expected-draft-version. The inventory combines finished scans of the selected Project environment into cookies, storage and third-party service requests with an advisory proposal. Workspace viewers can read it; reviewing and applying need Cookie draft authority. Inventory writes request both cookie:workspace:read and cookie:workspace:write for the selected Organization, because they read the site and current draft before updating them. They do not request publication authority.

Review input is {"items":[{"id":"…","expectedVersion":1,"action":"confirm"}]} with up to 100 items. confirm may set serviceKey (a listed option or null), vendor for a new service and purposeKey; ignore and reset take no extra fields. Confirm only what the evidence and the website owner support; never confirm a vendor or purpose from a name alone.

apply uses the draftVersion from list and saves the planned declaration rows and service changes: missing catalog presets and new custom services for confirmed vendors with an HTTPS privacy URL. Review the inventory's plan before applying it. It never publishes; review and publish the draft separately. A conflict means the draft changed.

Mailchimp contact forwarding

With the matching server, integrations mailchimp status|connect|refresh|disconnect --organization <id> manages the shared Organization connection. Connect returns the protected Services page: enter the key there for the exact Organization, never in chat or CLI arguments. Refresh/disconnect require --expected-revision; disconnect also requires --confirm.

forms integrations show|save|disable|deliveries|retry --form <id> --environment <slug> uses the selected common Project binding. Save takes --input <settings.json> containing the current expectedRevision; disable/retry take --expected-revision, and retry requires --delivery. Read settings first, retain unrelated mappings and use contact-only subscription: none unless marketing subscription with a real boolean consent field is explicitly intended. Deliveries can be filtered by --state or --submission; continue with --before from nextBefore. CLI inbox reads retain delivery status and accept --forwarding failed. These operations require dedicated administrator-only forwarding grants, not a general Forms workspace grant. A queued retry is not proof of delivery; read its terminal state. Individual submissions remain in Forms, contacts appear in the chosen Mailchimp audience. See the plugin's Mailchimp workflow for complete settings examples.

Pulse Checks

Page monitoring requires no repository files or SDK:

siteos pulse native save --name Homepage --slug home --kind http --path / --cadence 300

Attach ordinary Playwright tests through saved setup:

siteos pulse playwright attach --name Journeys --slug journeys --config playwright.config.ts --files 'tests/**/*.spec.ts'
siteos pulse playwright list --json
siteos pulse playwright publish --check <id> --dry-run
siteos pulse playwright publish --check <id>

Publication queues a verification run. Only a successful, nonempty result activates the snapshot. migrate --check <id> --revision <n> adopts an existing browser Check without replacing its ID, history or schedule. --auto-refresh uses the Project environment's GitHub repository and deployment evidence. Review environment suggestions with project repository deployments --installation <id> --repository <id> --refresh --json and save the intended binding. Native GitHub deployment integrations need no build change. Other systems run integrations github deployment report after successful publication, using their own GH_TOKEN/GITHUB_TOKEN with repository Deployments write access. The report includes the actual source SHA, environment, published URL and stable publication ID; it does not build or publish the site. No separate hosting connection or SiteOS CI login is needed. The optional --refresh-environment <name> overrides the binding's GitHub environment filter; --no-refresh disables refresh. Read saved setup and candidate state before changing revisions or

retrying failures. Legacy manifest/code commands remain supported. See the SiteOS plugin's setup guide.