@vox-ai/cli 0.1.0-beta.5 → 0.1.0-beta.50

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +64 -16
  2. package/bin/vox.cjs +80 -45
  3. package/package.json +9 -4
package/README.md CHANGED
@@ -9,7 +9,7 @@ The CLI is the durable authoring surface — what belongs in your repo, gets rev
9
9
  ## Install
10
10
 
11
11
  ```bash
12
- # npm (cross-platform, requires Node >= 20.17)
12
+ # npm (macOS, Linux, and Windows x64; requires Node >= 20.17)
13
13
  npm install -g @vox-ai/cli
14
14
 
15
15
  # npm pre-release channel
@@ -19,6 +19,8 @@ npm install -g @vox-ai/cli@beta
19
19
  brew install vox-public/tap/vox
20
20
  ```
21
21
 
22
+ On **Windows**, npm is the official install path: `npm install -g @vox-ai/cli@beta`, then run `vox` (or `vox.cmd`) from any terminal. There is no separate `.exe` or zip download to install.
23
+
22
24
  Verify the install:
23
25
 
24
26
  ```bash
@@ -65,11 +67,31 @@ A high-level map of the public surface. Run any command with `--help` for detail
65
67
  | --- | --- |
66
68
  | Auth & config | `auth login`, `auth whoami`, `auth switch`, `auth logout`, `config get/set` |
67
69
  | Get started | `init`, `doctor`, `guide coding-agent`, `guide flow` |
68
- | Discover offline | `docs search/show`, `skills list/show`, `schema list/get` |
70
+ | Discover offline | `docs search/show`, `skills list/show` (deprecated: vox.ai plugin 사용), `schema list/get` |
69
71
  | Authoring | `agent …`, `tool …`, `knowledge …` (plan, create, edit, validate, diff, push, version, promote) |
70
72
  | Sync | `sync status`, `sync import`, `sync bootstrap` |
73
+ | Organization | `org get/usage/members`, `org invoice list/get`, `org verification status`, `org create/delete`, `org api-key create/list/revoke` |
71
74
  | Multi-org | `org list`, `org switch`, `workspace init` |
72
- | Runtime & telephony | `chat`, `call …`, `number …`, `version`, `upgrade` |
75
+ | Runtime & telephony | `chat`, `call …`, `number …`, `widget …`, `version`, `upgrade` |
76
+
77
+ For sub-organization API keys, `--org` selects the authenticated caller while
78
+ `--sub-org` selects the organization in the API path:
79
+
80
+ ```bash
81
+ vox org api-key list --sub-org <sub-organization-id> --json
82
+ vox org api-key create --sub-org <sub-organization-id> --key-name production --allowed-ip 203.0.113.10 --allowed-ip 10.0.0.0/24 --json
83
+ vox org api-key revoke --sub-org <sub-organization-id> --key-name production --secret-key-suffix <last4> --yes --json
84
+ ```
85
+
86
+ The plaintext `data.api_key` from `create` is shown exactly once and cannot be
87
+ retrieved later; store it immediately in a secure secret store. It is never
88
+ written to CLI config, project state, telemetry, or error details. Each `list`
89
+ item contains only the key name, last-four suffix, creation time, last-used time,
90
+ and `allowed_ips`.
91
+
92
+ `--allowed-ip <ip|cidr>` (repeatable, up to 20; `'*'` allows every IP) restricts a
93
+ key to those addresses at `create`. The server validates and normalizes entries,
94
+ and an empty `allowed_ips` means no restriction.
73
95
 
74
96
  ## Using vox from Coding Agents
75
97
 
@@ -78,11 +100,13 @@ A high-level map of the public surface. Run any command with `--help` for detail
78
100
  ```bash
79
101
  vox guide coding-agent --json # the operating contract to follow
80
102
  vox docs search "<query>" --json # offline official docs
81
- vox skills list --json # design playbooks and workflow routing
103
+ vox skills list --json # deprecated: frozen snapshot, prefer the vox.ai plugin
82
104
  vox schema get <namespace> <schema-type> --json
83
105
  ```
84
106
 
85
- Every command accepts `--json` and emits a stable envelope (`{ ok, data }` on success, `{ ok: false, error: { code, message, … } }` on failure), so agents and automation can branch on results, read `error.details.hint`, and follow `related_commands`.
107
+ `vox skills list/show` is deprecated and frozen at a pinned snapshot; install the vox.ai plugin for current skills (`https://github.com/vox-public/plugin`).
108
+
109
+ Every command accepts `--json` and emits a stable envelope (`{ ok, data }` on success, `{ ok: false, error: { code, message, … } }` on failure), so agents and automation can branch on results, read `error.details.hint`, and follow `related_commands`. On the shared read-command error path (`llm`, `number`, `widget`, and other list/get-style commands) API failures promote the server `error.code` and `error.message` into that envelope (for example `VALIDATION_ERROR`); commands with their own error normalizers keep `API_REQUEST_FAILED`; 401/403/404 keep `AUTH_REQUIRED` / `API_FORBIDDEN` / the command's not-found mapping, and the original API body stays in `error.details`. Text mode prints a single line: `<action> failed with <status>: <code> — <message>`.
86
110
 
87
111
  ## Authentication
88
112
 
@@ -92,29 +116,53 @@ Every command accepts `--json` and emits a stable envelope (`{ ok, data }` on su
92
116
 
93
117
  ## Telemetry and Privacy
94
118
 
95
- Official builds send anonymous usage telemetry to help improve the CLI. It records coarse signals such as the command name, exit status, CLI version, and OS — never your arguments, file contents, tokens, agent data, or organization identifiers.
96
-
97
- Opt out at any time:
119
+ Official builds always send CLI usage and signed-in account metadata. Signed-in events identify the vox user and update the PostHog Person profile with the user's email, name, local profile, install ID, last login time, and current/default organization metadata. Usage properties include the command, exit status, CLI version, OS, and sanitized runtime signals.
98
120
 
99
- ```bash
100
- vox config set settings.telemetry disabled
101
- # or, per-process:
102
- DO_NOT_TRACK=1 vox …
103
- VOX_TELEMETRY_DISABLED=1 vox …
104
- ```
121
+ The CLI does not send prompts, paths, argument values, file contents, tokens, secrets, message content, customer data, hostnames, or free-text errors. Official builds do not provide a telemetry opt-out.
105
122
 
106
123
  Development and local builds never emit telemetry.
107
124
 
108
125
  ## Upgrade
109
126
 
110
- `vox upgrade` checks for a newer release and prints the upgrade command for how you installed it — it does not modify your installation itself. Run the printed command (or one of the below) to actually update:
127
+ `vox upgrade` is a package-manager aware upgrade assistant: it detects how vox was installed (npm, Homebrew, standalone, or unknown) and prints the exact upgrade command for that install. It never modifies your installation itself — run the printed command to update.
111
128
 
112
129
  ```bash
113
- vox upgrade # check for a newer version and print the upgrade command
130
+ vox upgrade # detect the install and print the exact upgrade command
131
+ vox upgrade --channel beta # check the beta channel
132
+ vox upgrade --json # structured output for scripts / coding agents
114
133
  npm install -g @vox-ai/cli@latest # update an npm install
115
134
  brew upgrade vox-public/tap/vox # update a Homebrew install
116
135
  ```
117
136
 
137
+ For Homebrew, `vox upgrade` distinguishes the newest upstream release from what the formula currently offers, so it won't tell you to `brew upgrade` before the formula has caught up. `vox upgrade --json` (schema `vox.ai.cli.upgrade.v2`) returns `status`, `confidence`, `actions`, and `verify_commands` so a coding agent can pick the next command without parsing human text.
138
+
139
+ ### Update notices
140
+
141
+ vox occasionally checks — at most once a day, when you run a command — whether a newer version is published, and caches the result locally (no daemon, no background process). When an update exists, it prints a single line to stderr on your next interactive run:
142
+
143
+ ```text
144
+ A newer vox.ai CLI is available: 0.1.0-beta.9
145
+ Run `vox upgrade` for the exact upgrade command.
146
+ ```
147
+
148
+ The check only queries the public npm registry — it is not telemetry and sends no account, organization, or auth information. It stays silent for `--json`, non-interactive shells, and CI, and never changes a command's exit code. **Homebrew installs are not nudged by this periodic notice** (npm alone cannot tell whether the formula has published the new version yet) — run `vox upgrade` or `brew outdated` for accurate Homebrew guidance. Turn it off with:
149
+
150
+ ```bash
151
+ VOX_NO_UPDATE_NOTIFIER=1 vox …
152
+ ```
153
+
154
+ ### macOS code signing
155
+
156
+ Official macOS binaries are signed with the company Developer ID Application identity, with a stable signing identity across builds:
157
+
158
+ ```text
159
+ Identifier=ai.vox.cli
160
+ TeamIdentifier=Z47Q5G9FA2
161
+ Authority=Developer ID Application: Fleek Corp. (Z47Q5G9FA2)
162
+ ```
163
+
164
+ Because the identity is stable, the macOS Keychain "Always Allow" choice keeps applying across `brew upgrade`s instead of re-prompting on every update. The first release that moves to the company Developer ID may prompt once (the identity changed from the previous one); after that it stays quiet while the identity is unchanged. This phase ships a Developer ID signature, not Apple notarization. Inspect it with `codesign -dvvv "$(which vox)"`.
165
+
118
166
  ## Support
119
167
 
120
168
  - Homepage: https://www.tryvox.co
package/bin/vox.cjs CHANGED
@@ -9,62 +9,97 @@ const platformPackages = {
9
9
  "darwin-arm64": "@vox-ai/cli-darwin-arm64",
10
10
  "darwin-x64": "@vox-ai/cli-darwin-x64",
11
11
  "linux-x64": "@vox-ai/cli-linux-x64",
12
+ "win32-x64": "@vox-ai/cli-win32-x64",
12
13
  };
13
14
 
14
- const artifact = `${process.platform}-${process.arch}`;
15
- const packageName = platformPackages[artifact];
16
-
17
- if (!packageName) {
18
- console.error(
19
- [
20
- `vox CLI does not ship a prebuilt npm binary for ${artifact}.`,
21
- "Install a supported macOS/Linux package or use the Homebrew formula on macOS.",
22
- ].join("\n"),
23
- );
24
- process.exit(1);
15
+ // Build the environment handed to the spawned platform binary. Injecting the
16
+ // install source lets `vox upgrade` report `install_source: "npm"` with high
17
+ // confidence even though the real executable lives under a platform package
18
+ // (@vox-ai/cli-<artifact>/bin/vox[.exe]). Pre-set values win so a parent
19
+ // wrapper / user override is respected.
20
+ function buildSpawnEnv(baseEnv, options) {
21
+ return {
22
+ ...baseEnv,
23
+ VOX_INSTALL_SOURCE: baseEnv.VOX_INSTALL_SOURCE || "npm",
24
+ VOX_EXECUTABLE_PATH: baseEnv.VOX_EXECUTABLE_PATH || options.scriptPath,
25
+ VOX_PLATFORM_PACKAGE: baseEnv.VOX_PLATFORM_PACKAGE || options.packageName,
26
+ VOX_PLATFORM_ARTIFACT: baseEnv.VOX_PLATFORM_ARTIFACT || options.artifact,
27
+ };
25
28
  }
26
29
 
27
- let binaryPath;
28
-
29
- try {
30
- binaryPath = join(dirname(require.resolve(`${packageName}/package.json`)), "bin", "vox");
31
- } catch (error) {
32
- console.error(
33
- [
34
- `The platform package ${packageName} is missing.`,
35
- "Reinstall @vox-ai/cli without omitting optional dependencies.",
36
- "",
37
- summarizeError(error),
38
- ].filter(Boolean).join("\n"),
39
- );
40
- process.exit(1);
30
+ function summarizeError(error) {
31
+ return error && typeof error.message === "string" ? error.message : String(error);
41
32
  }
42
33
 
43
- try {
44
- chmodSync(binaryPath, 0o755);
45
- } catch {
46
- // Best-effort for tarballs that did not preserve executable mode.
47
- }
34
+ function main() {
35
+ const artifact = `${process.platform}-${process.arch}`;
36
+ const packageName = platformPackages[artifact];
37
+
38
+ if (!packageName) {
39
+ console.error(
40
+ [
41
+ `vox CLI does not ship a prebuilt npm binary for ${artifact}.`,
42
+ "Supported platforms: macOS (arm64/x64), Linux x64, and Windows x64. On macOS you can also use the Homebrew formula.",
43
+ ].join("\n"),
44
+ );
45
+ process.exit(1);
46
+ }
48
47
 
49
- const child = spawn(binaryPath, process.argv.slice(2), {
50
- stdio: "inherit",
51
- });
48
+ // Bun compiles the Windows binary as `vox.exe`; every other platform ships an
49
+ // extension-less `vox`.
50
+ const binaryName = process.platform === "win32" ? "vox.exe" : "vox";
51
+ let binaryPath;
52
52
 
53
- child.on("error", (error) => {
54
- console.error(`Failed to start vox binary at ${binaryPath}: ${error.message}`);
55
- process.exit(1);
56
- });
53
+ try {
54
+ binaryPath = join(dirname(require.resolve(`${packageName}/package.json`)), "bin", binaryName);
55
+ } catch (error) {
56
+ console.error(
57
+ [
58
+ `The platform package ${packageName} is missing.`,
59
+ "Reinstall @vox-ai/cli without omitting optional dependencies.",
60
+ "",
61
+ summarizeError(error),
62
+ ]
63
+ .filter(Boolean)
64
+ .join("\n"),
65
+ );
66
+ process.exit(1);
67
+ }
57
68
 
58
- child.on("exit", (code, signal) => {
59
- if (signal) {
60
- process.kill(process.pid, signal);
61
- return;
69
+ try {
70
+ chmodSync(binaryPath, 0o755);
71
+ } catch {
72
+ // Best-effort for tarballs that did not preserve executable mode.
62
73
  }
63
74
 
64
- process.exit(code ?? 1);
65
- });
75
+ const child = spawn(binaryPath, process.argv.slice(2), {
76
+ stdio: "inherit",
77
+ env: buildSpawnEnv(process.env, {
78
+ packageName,
79
+ artifact,
80
+ scriptPath: process.argv[1],
81
+ }),
82
+ });
66
83
 
67
- function summarizeError(error) {
68
- return error && typeof error.message === "string" ? error.message : String(error);
84
+ child.on("error", (error) => {
85
+ console.error(`Failed to start vox binary at ${binaryPath}: ${error.message}`);
86
+ process.exit(1);
87
+ });
88
+
89
+ child.on("exit", (code, signal) => {
90
+ if (signal) {
91
+ process.kill(process.pid, signal);
92
+ return;
93
+ }
94
+
95
+ process.exit(code ?? 1);
96
+ });
69
97
  }
70
98
 
99
+ module.exports = { buildSpawnEnv, platformPackages };
100
+
101
+ // Only launch when executed as the bin entry (`vox`), not when imported by a
102
+ // unit test.
103
+ if (require.main === module) {
104
+ main();
105
+ }
package/package.json CHANGED
@@ -1,8 +1,12 @@
1
1
  {
2
2
  "name": "@vox-ai/cli",
3
- "version": "0.1.0-beta.5",
3
+ "version": "0.1.0-beta.50",
4
4
  "description": "vox.ai command-line workflow tools",
5
5
  "homepage": "https://www.tryvox.co",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/fleek-fitness/vox-cli.git"
9
+ },
6
10
  "license": "MIT",
7
11
  "bin": {
8
12
  "vox": "bin/vox.cjs"
@@ -13,9 +17,10 @@
13
17
  "LICENSE"
14
18
  ],
15
19
  "optionalDependencies": {
16
- "@vox-ai/cli-darwin-arm64": "0.1.0-beta.5",
17
- "@vox-ai/cli-darwin-x64": "0.1.0-beta.5",
18
- "@vox-ai/cli-linux-x64": "0.1.0-beta.5"
20
+ "@vox-ai/cli-darwin-arm64": "0.1.0-beta.50",
21
+ "@vox-ai/cli-darwin-x64": "0.1.0-beta.50",
22
+ "@vox-ai/cli-linux-x64": "0.1.0-beta.50",
23
+ "@vox-ai/cli-win32-x64": "0.1.0-beta.50"
19
24
  },
20
25
  "engines": {
21
26
  "node": ">=20.17.0"