@votrix-ai/cli 0.0.0-stage → 0.2.0
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 +189 -2
- package/SITE-TRACKING-CLI-DESIGN.md +117 -0
- package/dist/src/agent.js +366 -0
- package/dist/src/auth.js +197 -0
- package/dist/src/cli.js +148 -0
- package/dist/src/commands.js +117 -0
- package/dist/src/core.js +373 -0
- package/dist/src/integrations.js +143 -0
- package/dist/src/site.js +278 -0
- package/dist/src/tools.js +267 -0
- package/dist/src/zip.js +112 -0
- package/docs/API.md +95 -0
- package/docs/cli/account.md +76 -0
- package/docs/cli/agent.md +105 -0
- package/docs/cli/files.md +65 -0
- package/docs/cli/integrations.md +67 -0
- package/docs/cli/media.md +45 -0
- package/docs/cli/runs.md +44 -0
- package/docs/cli/scraper.md +45 -0
- package/docs/cli/seo.md +45 -0
- package/docs/cli/site.md +137 -0
- package/docs/cli/social.md +85 -0
- package/docs/cli/ui.md +45 -0
- package/package.json +30 -4
- package/production.json +5 -0
- package/skills/votrix/SKILL.md +97 -0
- package/skills/votrix/agents/openai.yaml +4 -0
package/dist/src/auth.js
ADDED
|
@@ -0,0 +1,197 @@
|
|
|
1
|
+
// Sign in once with Google, then keep only API keys: one per workspace for this
|
|
2
|
+
// device. The sign-in token is used to mint the keys and is never stored.
|
|
3
|
+
import { spawn } from "node:child_process";
|
|
4
|
+
import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
|
|
5
|
+
import { createServer } from "node:http";
|
|
6
|
+
import { hostname } from "node:os";
|
|
7
|
+
import { ApiError, clean, deviceId, note, usage, VotrixError } from "./core.js";
|
|
8
|
+
const CALLBACK = "/auth/callback";
|
|
9
|
+
const START = "/auth/start";
|
|
10
|
+
function pkce() {
|
|
11
|
+
const verifier = randomBytes(64).toString("base64url");
|
|
12
|
+
return { verifier, challenge: createHash("sha256").update(verifier).digest("base64url") };
|
|
13
|
+
}
|
|
14
|
+
function openBrowser(url) {
|
|
15
|
+
const [command, args] = process.platform === "darwin" ? ["open", [url]]
|
|
16
|
+
: process.platform === "win32" ? ["cmd", ["/c", "start", "", url]]
|
|
17
|
+
: ["xdg-open", [url]];
|
|
18
|
+
try {
|
|
19
|
+
spawn(command, args, { stdio: "ignore", detached: true }).on("error", () => { }).unref();
|
|
20
|
+
}
|
|
21
|
+
catch { /* the link is printed anyway */ }
|
|
22
|
+
}
|
|
23
|
+
function same(a, b) {
|
|
24
|
+
const x = Buffer.from(a), y = Buffer.from(b);
|
|
25
|
+
return x.length === y.length && timingSafeEqual(x, y);
|
|
26
|
+
}
|
|
27
|
+
// One-use loopback listener: /auth/start redirects to Google, /auth/callback
|
|
28
|
+
// receives the code. Both require the random nonce.
|
|
29
|
+
function awaitCode(port, timeoutMs, authorize, noBrowser) {
|
|
30
|
+
const nonce = randomBytes(32).toString("base64url");
|
|
31
|
+
return new Promise((done, fail) => {
|
|
32
|
+
let settled = false;
|
|
33
|
+
const reply = (res, status, text, location) => {
|
|
34
|
+
res.writeHead(status, {
|
|
35
|
+
"Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store", "Referrer-Policy": "no-referrer",
|
|
36
|
+
"Content-Security-Policy": "default-src 'none'; frame-ancestors 'none'", ...(location ? { Location: location } : {}),
|
|
37
|
+
});
|
|
38
|
+
res.end(text);
|
|
39
|
+
};
|
|
40
|
+
const server = createServer((req, res) => {
|
|
41
|
+
const host = `127.0.0.1:${server.address().port}`;
|
|
42
|
+
if (req.headers.host !== host)
|
|
43
|
+
return reply(res, 400, "Invalid sign-in callback address.");
|
|
44
|
+
const url = new URL(req.url ?? "/", `http://${host}`);
|
|
45
|
+
if (![START, CALLBACK].includes(url.pathname))
|
|
46
|
+
return reply(res, 404, "Not found.");
|
|
47
|
+
const state = url.searchParams.getAll("state");
|
|
48
|
+
if (state.length !== 1 || !same(state[0], nonce))
|
|
49
|
+
return reply(res, 400, "Sign-in verification failed.");
|
|
50
|
+
if (settled)
|
|
51
|
+
return reply(res, 409, "This sign-in callback has already been used.");
|
|
52
|
+
if (url.pathname === START)
|
|
53
|
+
return reply(res, 302, "Continue to Google sign-in.", authorizeUrl);
|
|
54
|
+
settled = true;
|
|
55
|
+
clearTimeout(timer);
|
|
56
|
+
if (url.searchParams.has("error")) {
|
|
57
|
+
reply(res, 400, "Sign-in failed or was canceled. Return to your terminal.");
|
|
58
|
+
server.close();
|
|
59
|
+
return fail(new VotrixError("unauthorized", "Google sign-in failed or was canceled. Run votrix login again."));
|
|
60
|
+
}
|
|
61
|
+
const code = url.searchParams.getAll("code");
|
|
62
|
+
if (code.length !== 1 || !code[0] || code[0].length > 4096) {
|
|
63
|
+
reply(res, 400, "No valid authorization code was received.");
|
|
64
|
+
server.close();
|
|
65
|
+
return fail(new VotrixError("unauthorized", "The sign-in callback had no valid code. Run votrix login again."));
|
|
66
|
+
}
|
|
67
|
+
reply(res, 200, "Votrix received your sign-in. Return to your terminal; you can close this page.");
|
|
68
|
+
server.close();
|
|
69
|
+
done(code[0]);
|
|
70
|
+
});
|
|
71
|
+
let authorizeUrl = "";
|
|
72
|
+
const timer = setTimeout(() => {
|
|
73
|
+
if (settled)
|
|
74
|
+
return;
|
|
75
|
+
settled = true;
|
|
76
|
+
server.close();
|
|
77
|
+
fail(new VotrixError("timeout", "Sign-in timed out.", "Run votrix login --no-browser and open the link on this computer."));
|
|
78
|
+
}, timeoutMs);
|
|
79
|
+
server.on("error", () => fail(usage(`Cannot listen on 127.0.0.1:${port}. Free the port or pass --port.`)));
|
|
80
|
+
server.listen(port, "127.0.0.1", () => {
|
|
81
|
+
const host = `127.0.0.1:${server.address().port}`;
|
|
82
|
+
authorizeUrl = authorize(`http://${host}${CALLBACK}?state=${encodeURIComponent(nonce)}`);
|
|
83
|
+
note(`Open this link in a browser on this computer and sign in with Google:\n${authorizeUrl}`);
|
|
84
|
+
if (!noBrowser)
|
|
85
|
+
openBrowser(`http://${host}${START}?state=${encodeURIComponent(nonce)}`);
|
|
86
|
+
note(`Waiting for sign-in (up to ${Math.round(timeoutMs / 1000)} seconds; Ctrl-C to cancel)...`);
|
|
87
|
+
});
|
|
88
|
+
});
|
|
89
|
+
}
|
|
90
|
+
export async function login(client, options) {
|
|
91
|
+
for (const name of ["VOTRIX_ACCESS_TOKEN", "VOTRIX_API_KEY"]) {
|
|
92
|
+
if (process.env[name])
|
|
93
|
+
throw usage(`Unset ${name} before running votrix login.`);
|
|
94
|
+
}
|
|
95
|
+
if (!client.cfg.publicKey)
|
|
96
|
+
throw usage("Set VOTRIX_SUPABASE_KEY to your public publishable key.");
|
|
97
|
+
const { verifier, challenge } = pkce();
|
|
98
|
+
const code = await awaitCode(options.port ?? 8765, (options.timeout ?? 180) * 1000, (callback) => `${client.cfg.auth}/auth/v1/authorize?` + new URLSearchParams({
|
|
99
|
+
provider: "google", redirect_to: callback, code_challenge: challenge, code_challenge_method: "s256",
|
|
100
|
+
}), Boolean(options.noBrowser));
|
|
101
|
+
const session = await (await client.raw("POST", `${client.cfg.auth}/auth/v1/token?grant_type=pkce`, {
|
|
102
|
+
headers: { apikey: client.cfg.publicKey }, body: { auth_code: code, code_verifier: verifier },
|
|
103
|
+
})).json();
|
|
104
|
+
const token = session?.access_token ?? session?.session?.access_token;
|
|
105
|
+
if (!token)
|
|
106
|
+
throw new VotrixError("unauthorized", "The sign-in response had no token.");
|
|
107
|
+
const user = await (await client.raw("GET", `${client.cfg.auth}/auth/v1/user`, {
|
|
108
|
+
headers: { apikey: client.cfg.publicKey }, auth: token,
|
|
109
|
+
})).json();
|
|
110
|
+
if (!user?.id)
|
|
111
|
+
throw new VotrixError("unauthorized", "The auth service returned no user. Sign-in was not saved.");
|
|
112
|
+
const who = { id: clean(user.id), ...(user.email ? { email: clean(user.email) } : {}) };
|
|
113
|
+
const { workspaces, keys } = await mintDeviceKeys(client, token);
|
|
114
|
+
const previous = client.state.read();
|
|
115
|
+
const state = previous.user?.id === who.id ? previous : {};
|
|
116
|
+
state.user = who;
|
|
117
|
+
state.workspaces = workspaces;
|
|
118
|
+
state.api_keys = keys;
|
|
119
|
+
if (!state.workspace_id || !keys[state.workspace_id]) {
|
|
120
|
+
delete state.workspace_id;
|
|
121
|
+
if (Object.keys(keys).length === 1)
|
|
122
|
+
state.workspace_id = Object.keys(keys)[0];
|
|
123
|
+
}
|
|
124
|
+
client.state.write(state);
|
|
125
|
+
const expiries = Object.values(keys).map((k) => k.expires_at).filter(Boolean).sort();
|
|
126
|
+
return { ...who, workspaces: workspaces.map((w) => w.display_name || w.id), keys_expire_at: expiries[0] ?? null };
|
|
127
|
+
}
|
|
128
|
+
// `/users/me` first: for a brand-new account it creates the first workspace.
|
|
129
|
+
export async function mintDeviceKeys(client, token) {
|
|
130
|
+
const backend = client.cfg.backend;
|
|
131
|
+
await client.raw("GET", `${backend}/users/me`, { auth: token });
|
|
132
|
+
const listed = await (await client.raw("GET", `${backend}/workspaces`, { auth: token })).json();
|
|
133
|
+
// Only workspaces the account belongs to: a super admin is listed every
|
|
134
|
+
// workspace in the installation, with an empty role where not a member.
|
|
135
|
+
const rows = Array.isArray(listed) ? listed.filter((row) => String(row?.role ?? "").trim()) : [];
|
|
136
|
+
if (!rows.length) {
|
|
137
|
+
throw new VotrixError("not_found", "This account has no workspace.", "Open the Votrix App once, then log in again.");
|
|
138
|
+
}
|
|
139
|
+
const device = deviceId();
|
|
140
|
+
const name = `CLI - ${clean(hostname()).slice(0, 60) || "unknown device"}`;
|
|
141
|
+
const workspaces = [];
|
|
142
|
+
const keys = {};
|
|
143
|
+
for (const row of rows) {
|
|
144
|
+
const minted = await (await client.raw("POST", `${backend}/workspaces/${row.id}/api-keys`, {
|
|
145
|
+
auth: token, body: { name, kind: "cli", device_id: device },
|
|
146
|
+
})).json();
|
|
147
|
+
if (!String(minted?.key ?? "").startsWith("vtx_")) {
|
|
148
|
+
throw new VotrixError("server", "The backend returned an invalid API key. Sign-in was not saved.");
|
|
149
|
+
}
|
|
150
|
+
workspaces.push({ id: row.id, display_name: clean(row.display_name ?? ""), role: clean(row.role ?? "") });
|
|
151
|
+
keys[row.id] = { key: minted.key, id: minted.id, prefix: minted.prefix, expires_at: minted.expires_at };
|
|
152
|
+
}
|
|
153
|
+
return { workspaces, keys };
|
|
154
|
+
}
|
|
155
|
+
export async function whoami(client, workspace) {
|
|
156
|
+
const current = await client.currentKey(workspace);
|
|
157
|
+
const summary = Object.fromEntries(["workspace_id", "workspace_name", "name", "kind", "prefix", "scopes",
|
|
158
|
+
"expires_at"].map((k) => [k, current[k]]));
|
|
159
|
+
if (process.env.VOTRIX_API_KEY)
|
|
160
|
+
return { source: "VOTRIX_API_KEY", ...summary };
|
|
161
|
+
const user = client.state.read().user ?? {};
|
|
162
|
+
return { ...user, ...summary };
|
|
163
|
+
}
|
|
164
|
+
// Revoke this device's keys on the backend, then forget them. The device id stays.
|
|
165
|
+
export async function logout(client) {
|
|
166
|
+
const keys = Object.values(client.state.read().api_keys ?? {});
|
|
167
|
+
let revoked = 0, unrevoked = 0;
|
|
168
|
+
for (const entry of keys) {
|
|
169
|
+
try {
|
|
170
|
+
await client.raw("DELETE", `${client.cfg.backend}/api-keys/current`, { auth: entry.key });
|
|
171
|
+
revoked++;
|
|
172
|
+
}
|
|
173
|
+
catch (error) {
|
|
174
|
+
if (error instanceof ApiError && error.status === 401)
|
|
175
|
+
revoked++; // already gone
|
|
176
|
+
else
|
|
177
|
+
unrevoked++;
|
|
178
|
+
}
|
|
179
|
+
}
|
|
180
|
+
client.state.clear();
|
|
181
|
+
return { logged_out: true, revoked_keys: revoked, unrevoked_keys: unrevoked,
|
|
182
|
+
environment_token_active: Boolean(process.env.VOTRIX_ACCESS_TOKEN || process.env.VOTRIX_API_KEY) };
|
|
183
|
+
}
|
|
184
|
+
// The workspaces this credential can act in.
|
|
185
|
+
export async function workspaces(client) {
|
|
186
|
+
if (process.env.VOTRIX_API_KEY) {
|
|
187
|
+
const current = await client.currentKey();
|
|
188
|
+
return [{ id: current.workspace_id, display_name: current.workspace_name, role: "" }];
|
|
189
|
+
}
|
|
190
|
+
if (process.env.VOTRIX_ACCESS_TOKEN)
|
|
191
|
+
return client.request("GET", "/workspaces");
|
|
192
|
+
const state = client.state.read();
|
|
193
|
+
const keys = state.api_keys ?? {};
|
|
194
|
+
if (!Object.keys(keys).length)
|
|
195
|
+
throw new VotrixError("unauthorized", "Run votrix login first.");
|
|
196
|
+
return (state.workspaces ?? []).filter((w) => keys[w.id]);
|
|
197
|
+
}
|
package/dist/src/cli.js
ADDED
|
@@ -0,0 +1,148 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
// votrix: hand work to Votrix employees and run Votrix tools. Built for other
|
|
3
|
+
// agents to call: one JSON object on stdout (errors too), progress on stderr,
|
|
4
|
+
// never a prompt. Exit codes: 0 answered, 1 failed, 2 bad usage.
|
|
5
|
+
import { realpathSync } from "node:fs";
|
|
6
|
+
import { fileURLToPath } from "node:url";
|
|
7
|
+
import { runAgent } from "./agent.js";
|
|
8
|
+
import { login, logout, whoami, workspaces } from "./auth.js";
|
|
9
|
+
import { Client, emit, errorBody, usage, uuidOf, VERSION, VotrixError } from "./core.js";
|
|
10
|
+
import { runTools } from "./tools.js";
|
|
11
|
+
import { help, resolveCommand } from "./commands.js";
|
|
12
|
+
const BOOLEAN = new Set(["no-browser", "no-wait", "no-track", "draft", "json", "help", "logs", "get-schema", "dry-run"]);
|
|
13
|
+
export function parse(argv) {
|
|
14
|
+
const positional = [];
|
|
15
|
+
const flags = {};
|
|
16
|
+
const set = (name, value) => {
|
|
17
|
+
if (name in flags)
|
|
18
|
+
flags[name] = [].concat(flags[name], value);
|
|
19
|
+
else
|
|
20
|
+
flags[name] = value;
|
|
21
|
+
};
|
|
22
|
+
for (let i = 0; i < argv.length; i++) {
|
|
23
|
+
const token = argv[i];
|
|
24
|
+
if (token === "--") {
|
|
25
|
+
positional.push(...argv.slice(i + 1));
|
|
26
|
+
break;
|
|
27
|
+
}
|
|
28
|
+
if (token === "-d" && positional.slice(0, 3).join(" ") === "tools integrations execute") {
|
|
29
|
+
if (!argv[i + 1] || argv[i + 1].startsWith("--"))
|
|
30
|
+
throw usage("-d requires a JSON object, @file, or - for stdin.");
|
|
31
|
+
set("data", argv[++i]);
|
|
32
|
+
}
|
|
33
|
+
else if (token.startsWith("--") && token.length > 2) {
|
|
34
|
+
const [name, inline] = token.slice(2).split(/=(.*)/s);
|
|
35
|
+
if (inline !== undefined)
|
|
36
|
+
set(name, inline);
|
|
37
|
+
else if (BOOLEAN.has(name) || i + 1 >= argv.length || (argv[i + 1].startsWith("--") && argv[i + 1].length > 2))
|
|
38
|
+
set(name, true);
|
|
39
|
+
else
|
|
40
|
+
set(name, argv[++i]);
|
|
41
|
+
}
|
|
42
|
+
else {
|
|
43
|
+
positional.push(token);
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
return { positional, flags };
|
|
47
|
+
}
|
|
48
|
+
function context(client, positional, flags) {
|
|
49
|
+
let chosen;
|
|
50
|
+
return {
|
|
51
|
+
client, positional, flags,
|
|
52
|
+
async workspace() {
|
|
53
|
+
if (chosen)
|
|
54
|
+
return chosen;
|
|
55
|
+
const given = flags.workspace ?? process.env.VOTRIX_WORKSPACE_ID ?? client.state.read().workspace_id;
|
|
56
|
+
if (given) {
|
|
57
|
+
if (!uuidOf(given))
|
|
58
|
+
throw usage("--workspace must be a workspace id.");
|
|
59
|
+
return (chosen = uuidOf(given));
|
|
60
|
+
}
|
|
61
|
+
const rows = await workspaces(client);
|
|
62
|
+
if (rows.length === 1)
|
|
63
|
+
return (chosen = rows[0].id);
|
|
64
|
+
throw usage("You have several workspaces. Choose one with votrix workspace use <id>, or pass --workspace <id>.", rows.map((w) => `${w.display_name} ${w.id}`).join("; "));
|
|
65
|
+
},
|
|
66
|
+
};
|
|
67
|
+
}
|
|
68
|
+
export async function main(argv) {
|
|
69
|
+
const { positional, flags } = parse(argv);
|
|
70
|
+
const [command, ...rest] = positional;
|
|
71
|
+
if (flags.version && !command)
|
|
72
|
+
return process.stdout.write(VERSION + "\n"), 0;
|
|
73
|
+
const path = [...positional];
|
|
74
|
+
if (flags.help && path.slice(0, 3).join(" ") === "tools site tracking")
|
|
75
|
+
path[2] = "track";
|
|
76
|
+
const resolved = resolveCommand(path);
|
|
77
|
+
if (resolved.command.usage === undefined && resolved.depth < path.length) {
|
|
78
|
+
throw usage(`Unknown command '${path.slice(0, resolved.depth + 1).join(" ")}'.`, help(resolved.command));
|
|
79
|
+
}
|
|
80
|
+
if (flags.help || resolved.command.usage === undefined) {
|
|
81
|
+
process.stdout.write(help(resolved.command) + "\n");
|
|
82
|
+
return flags.help ? 0 : 2;
|
|
83
|
+
}
|
|
84
|
+
const client = new Client();
|
|
85
|
+
const ctx = context(client, rest, flags);
|
|
86
|
+
switch (command) {
|
|
87
|
+
case "login":
|
|
88
|
+
emit(await login(client, { noBrowser: flags["no-browser"], port: flags.port ? Number(flags.port) : undefined,
|
|
89
|
+
timeout: flags.timeout ? Number(flags.timeout) : undefined }));
|
|
90
|
+
return 0;
|
|
91
|
+
case "logout":
|
|
92
|
+
emit(await logout(client));
|
|
93
|
+
return 0;
|
|
94
|
+
case "whoami":
|
|
95
|
+
emit(await whoami(client, process.env.VOTRIX_API_KEY ? undefined : await ctx.workspace()));
|
|
96
|
+
return 0;
|
|
97
|
+
case "workspaces":
|
|
98
|
+
emit({ workspaces: await workspaces(client) });
|
|
99
|
+
return 0;
|
|
100
|
+
case "credits": {
|
|
101
|
+
const workspace = await ctx.workspace();
|
|
102
|
+
const { balance, entries } = await client.request("GET", "/billing/balance", { workspace });
|
|
103
|
+
emit({ workspace_id: workspace, balance, recent: (entries ?? []).slice(0, 10) });
|
|
104
|
+
return 0;
|
|
105
|
+
}
|
|
106
|
+
case "workspace": {
|
|
107
|
+
if (rest[0] !== "use" || !uuidOf(rest[1]))
|
|
108
|
+
throw usage("Usage: votrix workspace use <workspace-id>");
|
|
109
|
+
const id = uuidOf(rest[1]);
|
|
110
|
+
if (!(await workspaces(client)).some((w) => w.id === id)) {
|
|
111
|
+
throw new VotrixError("not_found", "This credential cannot act in that workspace.", "Run votrix login to refresh your workspaces.");
|
|
112
|
+
}
|
|
113
|
+
client.state.update({ workspace_id: id });
|
|
114
|
+
emit({ workspace_id: id });
|
|
115
|
+
return 0;
|
|
116
|
+
}
|
|
117
|
+
case "agent": {
|
|
118
|
+
return runAgent({ ...ctx, positional: rest.slice(1) }, rest[0]);
|
|
119
|
+
}
|
|
120
|
+
case "tools": {
|
|
121
|
+
const [group, action] = rest;
|
|
122
|
+
// Integrations consumes the target (including "list") in its handler.
|
|
123
|
+
const nested = resolved.depth === 4 && group !== "integrations";
|
|
124
|
+
const sub = nested ? rest[2] : undefined;
|
|
125
|
+
return runTools({ ...ctx, positional: rest.slice(nested ? 3 : 2) }, group, action, sub);
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
throw usage(`Unknown command '${command}'.`, "votrix --help lists the commands.");
|
|
129
|
+
}
|
|
130
|
+
function invokedDirectly() {
|
|
131
|
+
try {
|
|
132
|
+
return Boolean(process.argv[1]) && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url);
|
|
133
|
+
}
|
|
134
|
+
catch {
|
|
135
|
+
return false;
|
|
136
|
+
}
|
|
137
|
+
}
|
|
138
|
+
const invoked = invokedDirectly();
|
|
139
|
+
if (invoked || process.env.VOTRIX_CLI_MAIN) {
|
|
140
|
+
process.on("SIGINT", () => {
|
|
141
|
+
process.stderr.write("\nStopped waiting. Work already started keeps going on Votrix; votrix agent get / votrix tools runs get picks it up.\n");
|
|
142
|
+
process.exit(130);
|
|
143
|
+
});
|
|
144
|
+
main(process.argv.slice(2)).then((code) => { process.exitCode = code; }, (error) => {
|
|
145
|
+
emit(errorBody(error));
|
|
146
|
+
process.exitCode = error instanceof VotrixError ? error.exitCode : 1;
|
|
147
|
+
});
|
|
148
|
+
}
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
export const commands = new Map();
|
|
2
|
+
function group(path, description) {
|
|
3
|
+
commands.set(path, { path, description });
|
|
4
|
+
}
|
|
5
|
+
function leaf(path, usage, description, result, example = "") {
|
|
6
|
+
commands.set(path, { path, usage, description, result, example });
|
|
7
|
+
}
|
|
8
|
+
group("", "Votrix accounts, employees and tools");
|
|
9
|
+
leaf("login", "[--no-browser] [--port N] [--timeout S]", "Sign in to Votrix with Google (default port 8765, timeout 180 seconds).", "Device credentials for the account's workspaces.", "--no-browser");
|
|
10
|
+
leaf("logout", "", "Revoke the saved device keys.", "Logout result.");
|
|
11
|
+
leaf("whoami", "", "Show the current identity and workspace.", "Account and credential metadata.");
|
|
12
|
+
leaf("workspaces", "", "List available workspaces.", "workspaces array.");
|
|
13
|
+
group("workspace", "Select the default workspace.");
|
|
14
|
+
leaf("workspace use", "ID", "Select a workspace by ID.", "workspace_id.", "WORKSPACE_ID");
|
|
15
|
+
leaf("credits", "", "Check workspace credit usage.", "balance and recent charges.");
|
|
16
|
+
group("agent", "Delegate tasks to Votrix employees.");
|
|
17
|
+
leaf("agent ls", "", "List available employees.", "Employee identifiers and roles.");
|
|
18
|
+
leaf("agent ask", "EMPLOYEE TASK|- [--file PATH|ID ...] [--session ID] [--out DIR] [--no-wait]", "Send a task and wait by default.", "Session ID and, after completion, reply and presented files.", 'rebecca "Review this brief" --file brief.pdf');
|
|
19
|
+
leaf("agent wait", "SESSION [--out DIR]", "Wait for the latest task.", "Session status, reply and presented files.", "SESSION_ID");
|
|
20
|
+
leaf("agent sessions", "[--employee NAME] [--limit N] [--before UPDATED_AT]", "List recent conversations.", "Session records.");
|
|
21
|
+
leaf("agent get", "SESSION", "Inspect a session without waiting.", "Session status.", "SESSION_ID");
|
|
22
|
+
leaf("agent files", "SESSION", "List output files.", "File metadata.", "SESSION_ID");
|
|
23
|
+
leaf("agent pull", "ASSET ... [--out DIR]", "Download output assets.", "Downloaded files and paths.", "ASSET_ID --out ./out");
|
|
24
|
+
leaf("agent history", "SESSION [--limit N] [--before SEQ]", "Read messages and presented files.", "History rows and pagination.", "SESSION_ID");
|
|
25
|
+
leaf("agent stop", "SESSION", "Interrupt a running session.", "Session and interruption result.", "SESSION_ID");
|
|
26
|
+
group("tools", "Run tools directly in a workspace.");
|
|
27
|
+
export const categories = ["media", "seo", "scraper", "ui"];
|
|
28
|
+
const descriptions = ["Generate media.", "Query SEO datasets.", "Collect data from supported sources.", "Run UI design tools."];
|
|
29
|
+
const examples = ["seedance", "keyword_metrics", "reddit-posts", "design"];
|
|
30
|
+
for (const [index, category] of categories.entries()) {
|
|
31
|
+
const path = `tools ${category}`;
|
|
32
|
+
group(path, descriptions[index]);
|
|
33
|
+
leaf(path + " list", "", "Discover available tools.", "Current catalog.");
|
|
34
|
+
leaf(path + " explore", "NAME [--mode MODE]", "Inspect supported parameters, outputs and price.", "Tool description and parameter schema.", examples[index]);
|
|
35
|
+
leaf(path + " run", "NAME [--mode MODE] [--input JSON|@FILE] [--PARAM VALUE ...] [--max-cost USD] [--out DIR] [--no-wait]", "Run a tool. Explore its inputs first. Waits by default.", "Run ID, status and available results or files.", examples[index] + " --input @input.json");
|
|
36
|
+
}
|
|
37
|
+
group("tools runs", "Inspect and manage tool runs.");
|
|
38
|
+
leaf("tools runs list", "[--category NAME] [--limit N]", "List recent runs (default limit 20).", "Run records.");
|
|
39
|
+
leaf("tools runs get", "ID [--out DIR] [--no-wait]", "Wait for a run or return its current state.", "Run status and available outputs.", "RUN_ID --no-wait");
|
|
40
|
+
leaf("tools runs stop", "ID", "Stop a run.", "Run status.", "RUN_ID");
|
|
41
|
+
group("tools files", "Upload, download and publish workspace files.");
|
|
42
|
+
leaf("tools files upload", "PATH ...", "Upload local files privately.", "Asset IDs and file metadata.", "./brief.pdf");
|
|
43
|
+
leaf("tools files get", "ASSET", "Inspect file metadata.", "File record.", "ASSET_ID");
|
|
44
|
+
leaf("tools files pull", "ASSET ... [--out DIR]", "Download workspace assets.", "Local paths.", "ASSET_ID --out ./out");
|
|
45
|
+
leaf("tools files publish", "ASSET|PATH --name NAME", "Publish a file at a permanent public URL.", "Publication information.", "./brief.pdf --name brief");
|
|
46
|
+
leaf("tools files library", "[--query TEXT] [--mime-group GROUP ...] [--before CURSOR] [--limit N]", "Search saved workspace files. Default limit 50.", "Matching file records.", "--query brief");
|
|
47
|
+
group("tools social", "Manage social accounts and posts.");
|
|
48
|
+
leaf("tools social accounts", "[--platform NAME]", "List connected social accounts.", "accounts array.");
|
|
49
|
+
group("tools social posts", "Draft, schedule and inspect posts.");
|
|
50
|
+
const postFlags = "[--file JSON_FILE|-] [--account ID ...] [--caption TEXT|--caption-file FILE] [--media URL|PATH|ASSET ...] [--thumbnail X] [--title TEXT] [--schedule-at TIME|--draft]";
|
|
51
|
+
leaf("tools social posts create", postFlags, "Create posts from a JSON file or account and content flags.", "Created post records.", '--account ACCOUNT_ID --caption "Launch day" --draft');
|
|
52
|
+
leaf("tools social posts update", "ID " + postFlags, "Update a post.", "Updated post record.", "POST_ID --file post.json");
|
|
53
|
+
leaf("tools social posts list", "[--account ID ...] [--status STATUS ...] [--limit N] [--offset N]", "List posts (default limit 50, offset 0).", "Post records.");
|
|
54
|
+
for (const [action, description, result] of [["get", "Inspect a post.", "Post record."], ["results", "Read publication results.", "Platform results."], ["cancel", "Cancel a post.", "Cancellation result."]]) {
|
|
55
|
+
leaf("tools social posts " + action, "ID", description, result, "POST_ID");
|
|
56
|
+
}
|
|
57
|
+
group("tools site", "Deploy websites and inspect visitor analytics.");
|
|
58
|
+
leaf("tools site list", "", "List workspace sites.", "Sites, addresses and live versions.");
|
|
59
|
+
leaf("tools site deploy", "DIR|ZIP --name SITE [--address SUB] [--no-track] [--no-wait]\n votrix tools site deploy --asset ID --name SITE [--no-track] [--no-wait]\n votrix tools site deploy --name SITE --version N [--no-wait]", "Deploy a version or restore an earlier one. Waits by default.", "Site, version, deployment status and available tracking metadata.", "./website --name my-site");
|
|
60
|
+
leaf("tools site versions", "SITE", "List deployment versions.", "Version history and live version.", "my-site");
|
|
61
|
+
leaf("tools site status", "SITE [--version N] [--logs]", "Inspect deployment progress.", "Deployment status and optional logs.", "my-site");
|
|
62
|
+
group("tools site env", "Manage site environment variables.");
|
|
63
|
+
leaf("tools site env list", "SITE", "List environment variable names.", "Variable names.", "my-site");
|
|
64
|
+
leaf("tools site env set", "SITE --from-file FILE|- [--target production|preview|all]", "Read KEY=VALUE lines from file or stdin. Default target is all.", "Environment update result.", "my-site --from-file site.env");
|
|
65
|
+
group("tools site domain", "Connect a domain and check its DNS.");
|
|
66
|
+
for (const action of ["add", "status"])
|
|
67
|
+
leaf("tools site domain " + action, "SITE DOMAIN", action === "add" ? "Connect a custom domain." : "Check domain status.", "Domain status and DNS information.", "my-site example.com");
|
|
68
|
+
group("tools site track", "Measure visits, clicks and outcomes on a Votrix site.");
|
|
69
|
+
for (const action of ["enable", "disable"])
|
|
70
|
+
leaf("tools site track " + action, "SITE", action === "enable" ? "Enable or upgrade visitor tracking." : "Disable visitor tracking.", "Tracking state and changed flag. A change may redeploy the live version.", "my-site");
|
|
71
|
+
const filters = "[--period 7d|30d|90d] [--by FIELD] [--where FIELD=VALUE[,VALUE...] ...]";
|
|
72
|
+
leaf("tools site track events", "SITE " + filters + " [--event NAME] [--search TEXT] [--limit N]", "Discover recorded names or group events. Defaults to 30d, grouped by name, limit 50 (max 200). Grouping by another field defaults to visit.", "data_status and rows with visitors and event count.", "my-site --by source");
|
|
73
|
+
leaf("tools site track funnel", "SITE --steps NAME,NAME[,NAME...] " + filters + " [--window 1h|1d|7d|30d]", "Count distinct browsers completing 2-5 steps in order. Defaults to period 30d and window 7d. Filters and grouping apply to the first step.", "data_status and steps (or groups) with visitors, of_previous_percent and of_first_percent.", "my-site --steps visit,login,signup_completed --where source=utm:instagram");
|
|
74
|
+
group("tools integrations", "Connect external apps such as Outlook or GA4 and run their actions.");
|
|
75
|
+
group("tools integrations toolkits", "Discover supported apps.");
|
|
76
|
+
leaf("tools integrations toolkits list", "", "List supported apps offline.", "toolkits with name and slug.");
|
|
77
|
+
group("tools integrations connections", "Inspect connected accounts.");
|
|
78
|
+
leaf("tools integrations connections list", "[--toolkit APP]", "List workspace connections.", "apps with accounts and status.", "--toolkit outlook");
|
|
79
|
+
leaf("tools integrations link", "APP [--no-browser] [--no-wait]", "Request the hosted OAuth URL. Open the returned URL to authorize.", "app, url, status, account_id and expires_at.", "outlook");
|
|
80
|
+
leaf("tools integrations search", "QUERY [--toolkits APP,APP] [--limit N]", "Search the live action catalog. Default limit 20.", "actions and needs_connection.", '"read my Gmail profile" --toolkits gmail');
|
|
81
|
+
leaf("tools integrations execute", "ACTION --get-schema\n votrix tools integrations execute ACTION [-d|--data JSON|@FILE|-] [--account ID] [--dry-run]", "Inspect the live schema, validate arguments or execute the action. Data defaults to {}.", "Schema mode returns input_schema and output_schema. Dry-run returns valid. Execution returns ok, action and data or error.", "GMAIL_GET_PROFILE --get-schema");
|
|
82
|
+
export function children(path) {
|
|
83
|
+
return [...commands.values()].filter(c => c.path && c.path.split(" ").slice(0, -1).join(" ") === path);
|
|
84
|
+
}
|
|
85
|
+
export function resolveCommand(words) {
|
|
86
|
+
let command = commands.get("");
|
|
87
|
+
let depth = 0;
|
|
88
|
+
while (depth < words.length && command.usage === undefined) {
|
|
89
|
+
const next = commands.get(words.slice(0, depth + 1).join(" "));
|
|
90
|
+
if (!next)
|
|
91
|
+
break;
|
|
92
|
+
command = next;
|
|
93
|
+
depth++;
|
|
94
|
+
}
|
|
95
|
+
return { command, depth };
|
|
96
|
+
}
|
|
97
|
+
export function help(command) {
|
|
98
|
+
const prefix = ("votrix " + command.path).trim();
|
|
99
|
+
const lines = [prefix + " — " + command.description, ""];
|
|
100
|
+
if (command.usage === undefined) {
|
|
101
|
+
for (const child of children(command.path)) {
|
|
102
|
+
lines.push(" " + child.path.padEnd(32) + " " + child.description);
|
|
103
|
+
}
|
|
104
|
+
if (command.path === "tools site track")
|
|
105
|
+
lines.push("", 'New deployments request tracking by default. Names use 1-40 lowercase letters, digits or underscores. Label clicks with data-track="login". Record a confirmed outcome with window.votrix.track("signup_completed").');
|
|
106
|
+
lines.push("", "Run " + prefix + " COMMAND --help for details.");
|
|
107
|
+
}
|
|
108
|
+
else {
|
|
109
|
+
lines.push("Usage", (" " + prefix + " " + command.usage).trimEnd(), "", "Returns " + command.result, "", "Example", (" " + prefix + " " + command.example).trimEnd());
|
|
110
|
+
}
|
|
111
|
+
if (["tools site track events", "tools site track funnel"].includes(command.path)) {
|
|
112
|
+
lines.push("", "Fields: source, campaign, medium, content, page, device, browser, os, country, city, day and name. Funnel grouping excludes name. Repeat --where to combine filters.");
|
|
113
|
+
}
|
|
114
|
+
if (!command.path)
|
|
115
|
+
lines.push("Use --workspace ID to select a workspace. VOTRIX_API_KEY supplies a saved API credential.");
|
|
116
|
+
return lines.join("\n");
|
|
117
|
+
}
|