@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 CHANGED
@@ -1,3 +1,193 @@
1
- # Temporary Holding Version
1
+ # Votrix AI CLI
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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.