@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.
- package/README.md +64 -16
- package/bin/vox.cjs +80 -45
- 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 (
|
|
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
|
|
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 #
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
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`
|
|
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 #
|
|
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
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
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
|
-
|
|
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
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
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
|
-
|
|
50
|
-
|
|
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
|
-
|
|
54
|
-
|
|
55
|
-
|
|
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
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
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.
|
|
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
|
-
|
|
68
|
-
|
|
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.
|
|
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.
|
|
17
|
-
"@vox-ai/cli-darwin-x64": "0.1.0-beta.
|
|
18
|
-
"@vox-ai/cli-linux-x64": "0.1.0-beta.
|
|
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"
|