SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillssiteos-cli

siteos-cli

General & other

View repository

Updated 10-16 08:05

About this skill

SiteOS CLI

Search supports independent indices per Project environment. Use search index list/create and pass --index ID to subsequent hosted Search operations. Named-index --install writes distinct credential variables and reports their names in safe installation metadata; do not overwrite another index's variables. See the Search skill's index workflow.

Read the shared execution contract once per task before choosing tools or resolving context, including when this skill is invoked directly. Apply the service-specific workflow below after that shared contract.

Use the single public package and binary:

npx --yes @siteoshq/cli@latest --help
npm install --global @siteoshq/cli
siteos --version

Node.js 22 or newer is required. Confirm the executable version and the needed subcommand in the task's working directory. A newer installation elsewhere does not update a different siteos resolved by PATH.

If a command is missing, use command -v siteos (or Get-Command siteos on PowerShell) and siteos --version, then run npx --yes @siteoshq/cli@latest --version and the needed --help. Keep the working directory, origin and SITEOS_HOME unchanged and use that same verified invocation for subsequent commands. Bare npx @siteoshq/cli may resolve an older local installation. If npm reports cache EACCES, pass --cache <new-user-owned-temporary-directory> to npm/npx and keep it for this task; do not use sudo or change ownership of the shared cache as part of a file workflow.

Run npx --yes @siteoshq/cli@latest health-check --json for read-only local diagnostics. It reports CLI/repository/reference readiness without contacting product APIs or reading runtime credentials.

Load references/command-reference.md whenever exact commands, flags, exit codes, state files, or environment overrides matter. That file is generated from the current CLI help and must not be edited manually.

Hosted installation

CLI 1.1.1 and newer defaults to https://app.siteos.sh. Upgrade older versions before starting production setup. Existing authentication and repository bindings preserve their selected origin; do not overwrite or copy them to switch installations. Authenticate at the intended origin.

For explicitly requested SiteOS staging work, set SITEOS_AUTH_BASE_URL, SITEOS_FORMS_PUBLIC_URL, and SITEOS_SEARCH_PUBLIC_URL to https://siteosapp.xui.se together before authentication. This selects a separate SiteOS installation, not a Project Environment.

Operating Rules

  • Use --json for agent and automation workflows whenever the command supports it.
  • Exit code 0 means success and 2 means invalid usage. Treat other nonzero codes as operational failures and preserve the command's safe error text.
  • Authenticate once through siteos auth; product commands obtain audience-bound service grants without exposing the durable Auth session.
  • Never print one-time tokens, sessions, service grants, runtime credentials, authorization headers, private binding files, or .env contents.
  • Private state belongs under ${SITEOS_HOME:-~/.siteos} and must not be committed.
  • siteos project use selects one common Project privately for the repository. siteos.config.json remains the tracked Pulse monitoring configuration. There are no service-private Project references; do not create .siteos/forms/project.json or .siteos/search/project.json.
  • Check project --help and integrations --help for --organization before the shared contract's exact-context handoff. Older CLIs need a release containing this capability or the explicitly requested local development build. Selection behavior belongs to the orchestrator's Project workflow.
  • Use siteos project for common selection, service setup and environments. Use siteos project environment use <slug> to switch every service together; Project settings own the name and per-environment URL. Never create a tracked .siteos/project.json.
  • Common Projects and the Cookie, Trace and Integrations commands require CLI 1.1.0 or newer and the matching SiteOS server. Check the installed help before using them; a source checkout does not prove the public package has been released.
  • If a command is absent from the generated reference, run the appropriate --help; do not invent it or call a private API as a substitute.

Storage files and website assets

Use siteos storage --help for private files, folders, verified transfers, versions, publication, expiring shares and trash. After selecting the exact Project environment, start with siteos storage status --json and siteos storage list --json. CLI 2.24.0 adds batch uploads, --dry-run and explicit duplicate-name policies through --on-conflict error|skip|replace. Upgrade older installations before using those flags. Follow the Storage workflow for conflict review, resumable upload receipts and separately authorized publication; a private upload never becomes a public website asset automatically.

Search crawler source review

CLI 2.11.0 adds search crawl preview, --decisions and --review-token for reviewing existing index matches and guarded publication. Use it with the matching Search backend and follow $siteos-search for source decisions. A ready crawl is not a published index; inspect the preview and resolve required choices before publication. Upgrade older CLIs before using this flow.

SEO repair workflow

CLI 2.1.0 adds seo repair, repeated seo recheck --url targets (up to 20), and the --resource guard used by Copy for agent. Older CLI versions cannot run those copied commands. Check the version and seo --help; upgrade with npm install --global @siteoshq/cli@latest or use npx @siteoshq/cli@latest. Read the SEO technical-audit workflow and verify the selected Organization, Project and environment before repair or recheck work. The 500-page full-audit maximum is server policy; upgrading the CLI does not change a saved 100-page setting.

Trace explorer

CLI 1.8.0 adds trace destinations, events, properties, issues, observations, issue show and observation show, plus tracking-plan publish --expected-draft-version. Use these only with the matching Trace server release. Read $siteos-trace for the investigation workflow and the distinction between a data layer source and observed analytics destinations. Lists return one page; preserve filters when using nextCursor. Commands do not poll or publish implicitly. An older CLI remains usable for its existing commands; upgrading it does not deploy the server or update a website's pinned Trace script.

Forms releases

For Zod projects, use CLI 2.45.0+ and forms deploy --source siteos.forms.ts with the published @siteoshq/forms 0.2+ root import with Zod 4. Keep ordinary Zod schemas and existing resolvers; do not add generated JSON, a custom converter or a website build hook. Existing manifest integrations retain forms deploy --manifest <path> until deliberately migrated. Publication requires an explicit Forms origin and publication-only SITEOS_FORMS_DEPLOYMENT_KEY. forms deployment-key issue|list|revoke manages that separate Environment authority through normal Auth grants. Submission credentials cannot publish. An agent can run publication locally as part of an authorized form change; hosting/CI setup is optional. Read ../siteos-forms/references/form-deployment.md for source validation, version pinning and rollback.

Cookie service discovery

Use cookie services list for the deployed catalog and custom-service schema and cookie discover for a bounded local browser/source/GTM-export inventory. Discovery never saves or publishes; the Cookie skill researches unknown providers and uses revision-checked draft save/publication. See service discovery. Verify these commands exist in the installed help before use.

Mailchimp forwarding

Check forms --help for forms integrations and integrations --help for mailchimp before using this feature; it also needs the matching server. See Mailchimp forwarding for scoped connection reads/refresh, form settings, safe retries and JSON input. Keys remain in the protected Services dialog. A successful queued retry does not establish provider delivery.