@capxul/cli 4.20.0-beta.1

package/README.md

@@ -0,0 +1,107 @@
+# Capxul CLI
+
+The CLI provides local diagnostics, an online backend check, and one global
+collection preference. It requires Node 24 or later on macOS or Linux.
+
+```sh
+capxul --help
+capxul --version
+capxul --completions bash
+capxul doctor --json
+capxul telemetry status --json
+capxul telemetry disable --json
+capxul telemetry enable --json
+capxul doctor --online --timeout-ms 30000 --json
+```
+
+Help, version, and completion do not read configuration or contact a server.
+`doctor` checks local configuration unless `--online` is present. An online
+check uses the public Capxul SDK and verifies the backend response nonce.
+It does not authenticate a person or submit a transaction.
+
+## Configuration
+
+| Variable                       | Use                                                                                                          |
+| ------------------------------ | ------------------------------------------------------------------------------------------------------------ |
+| `CAPXUL_CLI_HOME`              | Directory for global CLI settings. Defaults to `$XDG_CONFIG_HOME/capxul/cli`, or `$HOME/.config/capxul/cli`. |
+| `CAPXUL_PUBLISHABLE_KEY`       | Application publishable key, required for an online check.                                                   |
+| `CAPXUL_BOOTSTRAP_URL`         | Bootstrap origin. Defaults to `https://api.staging.capxul.com`. Convex Cloud origins are rejected.           |
+| `CAPXUL_POSTHOG_HOST`          | PostHog ingestion origin.                                                                                    |
+| `CAPXUL_POSTHOG_PROJECT_TOKEN` | Project ingestion token. Both PostHog variables are required for export.                                     |
+| `CAPXUL_TELEMETRY_DISABLED`    | Set to `true` to disable remote observation regardless of the saved preference.                              |
+
+Collection defaults to enabled. Local commands send no remote signals.
+`telemetry disable` saves one preference for the OS user and sends no final
+remote event. Already running CLI processes check the current preference before
+each export. Requests already sent cannot be recalled. `telemetry status`
+reports the stored preference, effective policy, configuration, and reason.
+
+Settings use a versioned JSON file in a directory with mode `0700`. The file has
+mode `0600`. Writes are atomic and serialize between processes. A later writer
+can recover an abandoned lock after the owning process exits. Invalid schemas,
+unsafe permissions, symlinks, and corrupt state produce a storage failure.
+
+## Output
+
+`--json` writes one version 1 envelope to stdout. Success contains `data`.
+Failure contains `error.code` and CLI-owned `error.message`. Each envelope has
+`command`, `invocationId`, and `outcome`. An invocation ID is null before a
+command starts. Human errors go to stderr.
+
+| Exit  | Meaning                                      |
+| ----- | -------------------------------------------- |
+| `0`   | Command completed                            |
+| `1`   | Unexpected defect                            |
+| `2`   | Invalid input, configuration, or local state |
+| `3`   | Authentication required                      |
+| `4`   | Authority refused                            |
+| `5`   | Dependency failure                           |
+| `124` | Online deadline exceeded                     |
+| `130` | Interrupted                                  |
+
+## Distribution
+
+The npm package is `@capxul/cli`. The Homebrew formula consumes that exact npm
+release, verifies its checksum, and installs Bash, Zsh, and Fish completions.
+Public installation status is in the
+[Homebrew tap](https://github.com/Xelmar-tech/homebrew-tap).
+
+After publication:
+
+```sh
+npm install -g @capxul/cli
+brew install xelmar-tech/tap/capxul
+```
+
+Homebrew installs Zsh completions in its standard completion directory. npm
+users can generate the same script:
+
+```sh
+mkdir -p ~/.zsh/completions
+capxul --completions zsh > ~/.zsh/completions/_capxul
+```
+
+Add these lines to `.zshrc`, before any existing `compinit` call. If the shell
+framework already calls `compinit`, add only the `fpath` line before it.
+
+```sh
+fpath=(~/.zsh/completions $fpath)
+autoload -Uz compinit
+compinit
+```
+
+Use `npm update -g @capxul/cli` or `brew upgrade xelmar-tech/tap/capxul` to update.
+Use one installer for the `capxul` executable to avoid conflicting PATH entries.
+
+## Development commands
+
+```sh
+vp test run apps/cli
+vp run --filter @capxul/cli check-types
+vp run --filter @capxul/cli build
+vp exec node --test --test-name-pattern='@capxul/cli' scripts/__tests__/pack-install-smoke.test.mjs
+```
+
+The last command installs the tarball outside the workspace and exercises the
+installed executable with isolated settings and a local HTTP server. The CI
+`CLI / Linux / Node 24.0.0` job runs this proof at the declared minimum version.