@votrix-ai/cli 0.0.0-stage → 0.2.1
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 +192 -2
- package/SITE-TRACKING-CLI-DESIGN.md +117 -0
- package/dist/src/agent.js +366 -0
- package/dist/src/auth.js +283 -0
- package/dist/src/cli.js +170 -0
- package/dist/src/commands.js +116 -0
- package/dist/src/core.js +373 -0
- package/dist/src/integrations.js +156 -0
- package/dist/src/site.js +278 -0
- package/dist/src/tools.js +289 -0
- package/dist/src/zip.js +112 -0
- package/docs/API.md +98 -0
- package/docs/cli/account.md +77 -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/README.md
CHANGED
|
@@ -1,3 +1,193 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Votrix AI CLI
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Hand work to Votrix employees and run Votrix tools from a terminal or from another agent (Claude Code, Codex, a script). Node.js 18.17+ on macOS, Linux and Windows. No runtime dependencies.
|
|
4
|
+
|
|
5
|
+
```bash
|
|
6
|
+
npm install -g @votrix-ai/cli # or run without installing: npx -y @votrix-ai/cli <command>
|
|
7
|
+
votrix login
|
|
8
|
+
votrix whoami
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
## Output contract
|
|
12
|
+
|
|
13
|
+
Commands print **one JSON object on stdout**, errors included:
|
|
14
|
+
|
|
15
|
+
```json
|
|
16
|
+
{"error": {"type": "not_found", "message": "No employee called 'nobody'.", "fix": "votrix agent ls lists them: ..."}}
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
Progress for people goes to stderr and `--help` prints plain text. Nothing ever prompts. Exit codes: `0` answered, `1` failed, `2` bad usage. Error types: `bad_input`, `not_found`, `unauthorized`, `forbidden`, `no_credits`, `busy`, `network`, `server`.
|
|
20
|
+
|
|
21
|
+
## Sign-in and keys
|
|
22
|
+
|
|
23
|
+
`votrix login` opens Google sign-in (PKCE with a one-use callback on `127.0.0.1:8765`), so the browser must run on the same computer. The CLI mints one `cli` API key per workspace for this device and discards the sign-in token. On a server, CI or a remote machine, create a CLI key for one workspace in the Votrix App and save it with `votrix login --key vtx_...`.
|
|
24
|
+
|
|
25
|
+
Keys live in `~/.config/votrix` (`%APPDATA%\votrix` on Windows) with mode `0600` and last 90 days; log in again to renew them. A random device id in the same folder makes a new login replace this device's earlier keys. `votrix logout` revokes the keys on the backend and removes local state.
|
|
26
|
+
|
|
27
|
+
```bash
|
|
28
|
+
votrix login # Google sign-in in a browser on this computer
|
|
29
|
+
votrix login --no-browser # print the link only
|
|
30
|
+
votrix login --key vtx_... # save a key created in the Votrix App (servers, CI, remote machines)
|
|
31
|
+
votrix whoami # with several workspaces and none chosen, lists them
|
|
32
|
+
votrix workspace use <workspace-id>
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
| Variable | Purpose |
|
|
36
|
+
|---|---|
|
|
37
|
+
| `VOTRIX_API_KEY` | Use this key (`vtx_...`) instead of the saved login; it acts in its workspace with its scopes |
|
|
38
|
+
| `VOTRIX_WORKSPACE_ID` | Default workspace (a `--workspace` flag overrides it) |
|
|
39
|
+
| `VOTRIX_BACKEND_URL`, `VOTRIX_SUPABASE_URL`, `VOTRIX_SUPABASE_KEY` | Another environment (HTTPS, or HTTP on localhost) |
|
|
40
|
+
| `VOTRIX_CONFIG_DIR` | Where keys and the device id are kept |
|
|
41
|
+
|
|
42
|
+
## Hand work to an employee
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
votrix agent ls # id, name, slug, role
|
|
46
|
+
votrix agent ask rebecca 'Make a 30-second launch video' --file ./product.png --out ./out
|
|
47
|
+
votrix agent ask rebecca 'Make it vertical' --session <id> --out ./out
|
|
48
|
+
printf 'Line one\nLine two\n' | votrix agent ask rebecca -
|
|
49
|
+
votrix agent sessions --employee rebecca # conversations, most recent first
|
|
50
|
+
votrix agent get <session> # where it stands, without waiting
|
|
51
|
+
votrix agent files <session> # every file in the session's outputs folder
|
|
52
|
+
votrix agent pull <asset-id> [<asset-id> ...] --out ./out
|
|
53
|
+
votrix agent history <session> --limit 20 [--before <seq>]
|
|
54
|
+
votrix agent stop <session>
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
`ask` starts a new session (or continues `--session`) and **blocks until the whole session is done**: the employee's turns, its subagents, and background jobs such as a render that wake it again. It decides "done" with the backend's `GET /sessions/{id}/status`; a quiet stream during a long job is a poll, not a failure. Run it in the background if the caller cannot wait. Ctrl-C only stops waiting: the employee keeps working, and `get` picks it up.
|
|
58
|
+
|
|
59
|
+
```json
|
|
60
|
+
{"session_id": "…", "employee": {"id": "…", "name": "Rebecca"}, "status": "idle", "reply": "Your video is ready",
|
|
61
|
+
"presented": [{"asset_id": "…", "filename": "launch.mp4", "kind": "file", "size_bytes": 48000000,
|
|
62
|
+
"path": "out/launch.mp4"}]}
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
`status` is `idle` (done) or `failed`. `presented` holds the files the employee handed over in this task only; `--out` downloads them (a website or video project comes as its `<name>.website.zip` / `<name>.video.zip`). `files` lists everything in the session's outputs folder; pull any of it by asset id. `--file` takes a local path (uploaded, up to 500 MiB) or any asset id in the workspace, from any session. `history` pages back with the `before` it returns.
|
|
66
|
+
|
|
67
|
+
## Tools
|
|
68
|
+
|
|
69
|
+
| Command group | Commands |
|
|
70
|
+
| --- | --- |
|
|
71
|
+
| [`votrix`](docs/cli/account.md) | `login`, `logout`, `whoami`, `workspaces`, `workspace use`, `credits` |
|
|
72
|
+
| [`votrix agent`](docs/cli/agent.md) | `ls`, `ask`, `wait`, `sessions`, `get`, `files`, `pull`, `history`, `stop` |
|
|
73
|
+
| [`votrix tools media`](docs/cli/media.md) | `list`, `explore`, `run` |
|
|
74
|
+
| [`votrix tools seo`](docs/cli/seo.md) | `list`, `explore`, `run` |
|
|
75
|
+
| [`votrix tools scraper`](docs/cli/scraper.md) | `list`, `explore`, `run` |
|
|
76
|
+
| [`votrix tools ui`](docs/cli/ui.md) | `list`, `explore`, `run` |
|
|
77
|
+
| [`votrix tools runs`](docs/cli/runs.md) | `list`, `get`, `stop` |
|
|
78
|
+
| [`votrix tools files`](docs/cli/files.md) | `upload`, `get`, `pull`, `publish`, `library` |
|
|
79
|
+
| [`votrix tools social`](docs/cli/social.md) | `accounts`, `posts create`, `posts update`, `posts list`, `posts get`, `posts results`, `posts cancel` |
|
|
80
|
+
| [`votrix tools site`](docs/cli/site.md) | `list`, `deploy`, `versions`, `status`, `env list`, `env set`, `domain add`, `domain status`, `track enable`, `track disable`, `track events`, `track funnel` |
|
|
81
|
+
| [`votrix tools integrations`](docs/cli/integrations.md) | `toolkits list`, `connections`, `link`, `search`, `execute` |
|
|
82
|
+
|
|
83
|
+
### Command guides
|
|
84
|
+
|
|
85
|
+
- [Account and workspace](docs/cli/account.md)
|
|
86
|
+
- [Employees and sessions](docs/cli/agent.md)
|
|
87
|
+
- [Media tools](docs/cli/media.md)
|
|
88
|
+
- [SEO tools](docs/cli/seo.md)
|
|
89
|
+
- [Scraper tools](docs/cli/scraper.md)
|
|
90
|
+
- [UI tools](docs/cli/ui.md)
|
|
91
|
+
- [Tool runs](docs/cli/runs.md)
|
|
92
|
+
- [Social publishing](docs/cli/social.md)
|
|
93
|
+
- [Workspace files](docs/cli/files.md)
|
|
94
|
+
- [Website deployment](docs/cli/site.md)
|
|
95
|
+
- [Connected applications](docs/cli/integrations.md)
|
|
96
|
+
- [Site analytics](SITE-TRACKING-CLI-DESIGN.md)
|
|
97
|
+
- [HTTP API reference](docs/API.md)
|
|
98
|
+
|
|
99
|
+
Use `votrix tools --help` or `votrix tools GROUP --help` for flags.
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
votrix tools media list # models, aliases, defaults, as they are today
|
|
103
|
+
votrix tools media explore seedance # modes, parameters, price
|
|
104
|
+
votrix tools media run seedance --mode text_to_video --prompt 'A calm sea at dawn' --duration 5 --out ./out
|
|
105
|
+
votrix tools media run nano-banana-2.1 --prompt 'A red bicycle' --image-url ./ref.png --out ./out
|
|
106
|
+
votrix tools seo explore keyword_metrics
|
|
107
|
+
votrix tools seo run keyword_metrics --keywords '["restaurant pos"]'
|
|
108
|
+
votrix tools scraper run reddit-posts --where r/SEO --query 'new site not ranking' --limit 20
|
|
109
|
+
votrix tools ui run design --site-type 'online sneaker store' --story 'choosing a size, then adding to cart' --out ./out
|
|
110
|
+
votrix tools runs list | get <run> --out ./out | stop <run>
|
|
111
|
+
```
|
|
112
|
+
|
|
113
|
+
Categories are fixed (`media`, `seo`, `scraper`, `ui`); what is inside them is read from the backend, so models can change without a new CLI. Media models have family aliases (`seedance`, `kling`) and domain defaults (`image`, `video`, `audio`). Every scraper source and SEO dataset states the exact fields a row carries (`returns` in `explore`).
|
|
114
|
+
|
|
115
|
+
Any `--<parameter> VALUE` goes into the run's input (`--image-url` becomes `image_url`, JSON values are parsed, a repeated flag is a list); `--input '{...}'` or `--input @file.json` gives it all at once. A value that is a local file is uploaded and passed as `asset:<id>`. `run` blocks until the run is done; `--no-wait` returns the run id at once, and `--max-credits N` refuses a run estimated above N credits, or one whose price cannot be worked out first. `explore` shows each mode's `credits.at_defaults`; a run returns `estimate_credits` and, once finished, the `credits` charged. Runs are billed to the workspace's credits (`--max-cost USD` from 0.2.0 is still accepted).
|
|
116
|
+
|
|
117
|
+
```bash
|
|
118
|
+
votrix tools social accounts --platform youtube
|
|
119
|
+
votrix tools social posts create --account <id> --caption 'Launch day' --media ./launch.mp4 --title 'Launch' --schedule-at 2030-01-01T12:00:00Z
|
|
120
|
+
votrix tools social posts list
|
|
121
|
+
votrix tools files upload ./brief.pdf
|
|
122
|
+
votrix tools files library --query launch
|
|
123
|
+
```
|
|
124
|
+
|
|
125
|
+
## Sites and visitor analytics
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
votrix tools site deploy ./website --name my-site
|
|
129
|
+
votrix tools site track events my-site --by source
|
|
130
|
+
votrix tools site track funnel my-site --steps visit,login,signup_completed --where source=utm:instagram
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
Deploy requests tracking by default. Use `--no-track` to opt out or
|
|
134
|
+
`site track enable` to install or upgrade tracking on a live site. See
|
|
135
|
+
[Site tracking CLI](SITE-TRACKING-CLI-DESIGN.md) for website instrumentation,
|
|
136
|
+
query inputs, and JSON replies.
|
|
137
|
+
|
|
138
|
+
## Connected apps
|
|
139
|
+
|
|
140
|
+
The toolkit catalog is available offline. Connection, search, and execution
|
|
141
|
+
commands use the Votrix backend and the selected workspace. A scoped Votrix
|
|
142
|
+
API key needs `tools:integrations`.
|
|
143
|
+
|
|
144
|
+
```bash
|
|
145
|
+
votrix tools integrations --help
|
|
146
|
+
votrix tools integrations toolkits list
|
|
147
|
+
votrix tools integrations connections --toolkit gmail
|
|
148
|
+
votrix tools integrations link gmail --no-browser
|
|
149
|
+
votrix tools integrations search "find unread emails" --toolkit gmail
|
|
150
|
+
votrix tools integrations execute GMAIL_FETCH_EMAILS --get-schema
|
|
151
|
+
votrix tools integrations execute GMAIL_FETCH_EMAILS --dry-run -d '{"query":"is:unread"}'
|
|
152
|
+
votrix tools integrations execute GMAIL_FETCH_EMAILS -d '{"query":"is:unread"}'
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
| Command | Input | JSON output |
|
|
156
|
+
| --- | --- | --- |
|
|
157
|
+
| `toolkits list` | No arguments | `toolkits` with each app's `slug` and `name` |
|
|
158
|
+
| `link` | App slug | `app`, `status`, hosted OAuth `url`, `account_id`, `expires_at` |
|
|
159
|
+
| `connections` | Optional `--toolkit APP` | `apps` with each `toolkit`, its linked accounts and their statuses |
|
|
160
|
+
| `search` | Query, optional `--toolkit APP` and `--limit N` | `actions` with executable action slugs, and `needs_connection` |
|
|
161
|
+
| `execute --get-schema` | Action slug | `parameters` (name, type, required, description), `rules` that span parameters, and the raw `input_schema` and `output_schema` |
|
|
162
|
+
| `execute --dry-run` | Action slug, arguments and optional account ID | `valid` and the `account` it would run as; refuses when several accounts are connected and none is chosen |
|
|
163
|
+
| `execute` | Action slug, arguments and optional account ID | `ok`, `action`, and provider `data` or an `error` |
|
|
164
|
+
|
|
165
|
+
Give the authorization URL returned by `link` to the user. Run `connections` after
|
|
166
|
+
they finish connecting. Use the action name and input schema returned by the
|
|
167
|
+
backend. For multiple accounts, pass the selected account ID using `--account`.
|
|
168
|
+
`--data` (or `-d`) accepts strict JSON, `@file.json`, or `-` for stdin.
|
|
169
|
+
Use `toolkits list` for app names and slugs. The catalog contains Gmail,
|
|
170
|
+
Outlook, Google Sheets, HubSpot, Google Calendar, Calendly, Slack, Search
|
|
171
|
+
Console, GA4, Semrush MCP, and Ahrefs MCP.
|
|
172
|
+
OAuth makes the connection available. Each app still controls what the account
|
|
173
|
+
can do through its granted permissions, roles, subscription, and limits.
|
|
174
|
+
|
|
175
|
+
## Use with Claude Code / Codex
|
|
176
|
+
|
|
177
|
+
The skill is in [`skills/votrix/SKILL.md`](skills/votrix/SKILL.md). Link it into the tools' skill folders:
|
|
178
|
+
|
|
179
|
+
```bash
|
|
180
|
+
mkdir -p ~/.claude/skills ~/.agents/skills
|
|
181
|
+
ln -s "$PWD/skills/votrix" ~/.claude/skills/votrix
|
|
182
|
+
ln -s "$PWD/skills/votrix" ~/.agents/skills/votrix
|
|
183
|
+
```
|
|
184
|
+
|
|
185
|
+
## Development
|
|
186
|
+
|
|
187
|
+
```bash
|
|
188
|
+
npm install
|
|
189
|
+
npm test # builds, then runs the CLI against a local fake backend
|
|
190
|
+
node dist/src/cli.js --help
|
|
191
|
+
```
|
|
192
|
+
|
|
193
|
+
Tests never call production. Signed storage URLs never receive the key, redirects are not followed with credentials, and server text is stripped of terminal escapes.
|
|
@@ -0,0 +1,117 @@
|
|
|
1
|
+
# Site tracking CLI
|
|
2
|
+
|
|
3
|
+
Use `votrix tools site track --help` to discover the tracking commands and the
|
|
4
|
+
browser API. The backend scopes queries to the selected workspace and site.
|
|
5
|
+
A scoped Votrix API key needs `tools:sites`.
|
|
6
|
+
|
|
7
|
+
## Deploy and instrument
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
votrix tools site deploy ./website --name my-site
|
|
11
|
+
votrix tools site track enable my-site
|
|
12
|
+
votrix tools site track disable my-site
|
|
13
|
+
votrix tools site status my-site
|
|
14
|
+
```
|
|
15
|
+
|
|
16
|
+
New deployments request tracking by default. Pass `--no-track` to skip it.
|
|
17
|
+
Inspect the deployment's `tracking` result to confirm that the backend
|
|
18
|
+
installed the collector. Enable and disable may redeploy the live version.
|
|
19
|
+
They return `site`, `version`, `tracking`, and `changed`, with deployment
|
|
20
|
+
`status` when a redeployment starts.
|
|
21
|
+
|
|
22
|
+
The collector records page visits as `visit`. Add a label to the actual
|
|
23
|
+
control to record a click.
|
|
24
|
+
|
|
25
|
+
```html
|
|
26
|
+
<a href="/login" data-track="login">Login</a>
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
On the signup success path, after the app confirms signup, record the outcome.
|
|
30
|
+
|
|
31
|
+
```js
|
|
32
|
+
window.votrix?.track?.("signup_completed");
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Use 1–40 lowercase ASCII letters, digits, or underscores. Reserve `visit`
|
|
36
|
+
for page views and use different names for clicks and outcomes. The collector
|
|
37
|
+
also recognizes the older `data-votrix-cta` attribute. Enable tracking to
|
|
38
|
+
upgrade an older collector before using `data-track` and `votrix.track()`.
|
|
39
|
+
Pass only the event name. For Instagram traffic, link to
|
|
40
|
+
`https://example.com/?utm_source=instagram&utm_campaign=bio`.
|
|
41
|
+
|
|
42
|
+
## Query events
|
|
43
|
+
|
|
44
|
+
```bash
|
|
45
|
+
votrix tools site track events my-site --period 30d
|
|
46
|
+
votrix tools site track events my-site --by source --event login --limit 20
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
| Input | Meaning |
|
|
50
|
+
| --- | --- |
|
|
51
|
+
| `SITE` | The workspace's site name |
|
|
52
|
+
| `--period` | `7d`, `30d`, or `90d`. Default `30d` |
|
|
53
|
+
| `--by` | A grouping field. Default `name` |
|
|
54
|
+
| `--event` | Event to count for a grouping other than `name`. Default `visit` in those groupings |
|
|
55
|
+
| `--where FIELD=VALUE[,VALUE...]` | Exact values. Repeat to add fields or values |
|
|
56
|
+
| `--search` | Case-insensitive substring of the grouping value |
|
|
57
|
+
| `--limit` | 1–200 rows. Default 50 |
|
|
58
|
+
|
|
59
|
+
Example stdout (selected fields):
|
|
60
|
+
|
|
61
|
+
```json
|
|
62
|
+
{
|
|
63
|
+
"site": "my-site",
|
|
64
|
+
"period": "30d",
|
|
65
|
+
"by": "name",
|
|
66
|
+
"data_status": "available",
|
|
67
|
+
"rows": [
|
|
68
|
+
{"name": "visit", "kind": "visit", "visitors": 120, "count": 160},
|
|
69
|
+
{"name": "login", "kind": "click", "visitors": 35, "count": 39}
|
|
70
|
+
],
|
|
71
|
+
"has_more": false
|
|
72
|
+
}
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
`visitors` measures distinct anonymous browser IDs and `count` measures
|
|
76
|
+
recorded events.
|
|
77
|
+
|
|
78
|
+
## Query an ordered funnel
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
votrix tools site track funnel my-site \
|
|
82
|
+
--steps visit,login,signup_completed \
|
|
83
|
+
--where source=utm:instagram --period 30d --window 7d
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
Give 2–5 comma-separated event names in order. The period defaults to `30d`
|
|
87
|
+
and the window defaults to `7d` from the first step. Valid windows are `1h`,
|
|
88
|
+
`1d`, `7d`, and `30d`. Filters apply to the first step, so a browser that
|
|
89
|
+
first arrived via Instagram can still count if it returned directly to sign up.
|
|
90
|
+
Use `--by source` to compare groups using the first step's source.
|
|
91
|
+
|
|
92
|
+
Grouping and filter fields are `name`, `source`, `campaign`, `medium`,
|
|
93
|
+
`content`, `page`, `device`, `browser`, `os`, `country`, `city`, and `day`.
|
|
94
|
+
Funnel grouping accepts every field except `name`. For sources, use the exact
|
|
95
|
+
labels returned by the events command, such as `utm:instagram`, `direct` or
|
|
96
|
+
`referrer:example.com`.
|
|
97
|
+
|
|
98
|
+
Example stdout (selected fields):
|
|
99
|
+
|
|
100
|
+
```json
|
|
101
|
+
{
|
|
102
|
+
"site": "my-site",
|
|
103
|
+
"period": "30d",
|
|
104
|
+
"window": "7d",
|
|
105
|
+
"filters_apply_to": "first_step",
|
|
106
|
+
"data_status": "available",
|
|
107
|
+
"steps": [
|
|
108
|
+
{"name": "visit", "visitors": 120, "of_previous_percent": 100, "of_first_percent": 100},
|
|
109
|
+
{"name": "login", "visitors": 35, "of_previous_percent": 29.2, "of_first_percent": 29.2},
|
|
110
|
+
{"name": "signup_completed", "visitors": 12, "of_previous_percent": 34.3, "of_first_percent": 10}
|
|
111
|
+
]
|
|
112
|
+
}
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
Grouped funnels return `groups` with their own `steps`. Queries can return
|
|
116
|
+
`data_status: "not_installed"` or `"no_events"`. Check installation and
|
|
117
|
+
record a real test visit and interaction before interpreting those results.
|