@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/docs/cli/site.md
ADDED
|
@@ -0,0 +1,137 @@
|
|
|
1
|
+
# Website deployment
|
|
2
|
+
|
|
3
|
+
Deploy a directory containing index.html, a zip archive, or a previously uploaded archive.
|
|
4
|
+
|
|
5
|
+
## Commands
|
|
6
|
+
|
|
7
|
+
### `votrix tools site list`
|
|
8
|
+
|
|
9
|
+
List workspace sites.
|
|
10
|
+
|
|
11
|
+
```text
|
|
12
|
+
votrix tools site list
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Returns Sites, addresses and live versions.
|
|
16
|
+
|
|
17
|
+
### `votrix tools site deploy`
|
|
18
|
+
|
|
19
|
+
Deploy a version or restore an earlier one. Waits by default.
|
|
20
|
+
|
|
21
|
+
```text
|
|
22
|
+
votrix tools site deploy DIR|ZIP --name SITE [--address SUB] [--no-track] [--no-wait]
|
|
23
|
+
votrix tools site deploy --asset ID --name SITE [--no-track] [--no-wait]
|
|
24
|
+
votrix tools site deploy --name SITE --version N [--no-wait]
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Returns Site, version, deployment status and available tracking metadata.
|
|
28
|
+
|
|
29
|
+
### `votrix tools site versions`
|
|
30
|
+
|
|
31
|
+
List deployment versions.
|
|
32
|
+
|
|
33
|
+
```text
|
|
34
|
+
votrix tools site versions SITE
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
Returns Version history and live version.
|
|
38
|
+
|
|
39
|
+
### `votrix tools site status`
|
|
40
|
+
|
|
41
|
+
Inspect deployment progress.
|
|
42
|
+
|
|
43
|
+
```text
|
|
44
|
+
votrix tools site status SITE [--version N] [--logs]
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
Returns Deployment status and optional logs.
|
|
48
|
+
|
|
49
|
+
### `votrix tools site env list`
|
|
50
|
+
|
|
51
|
+
List environment variable names.
|
|
52
|
+
|
|
53
|
+
```text
|
|
54
|
+
votrix tools site env list SITE
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Returns Variable names.
|
|
58
|
+
|
|
59
|
+
### `votrix tools site env set`
|
|
60
|
+
|
|
61
|
+
Read KEY=VALUE lines from file or stdin. Default target is all.
|
|
62
|
+
|
|
63
|
+
```text
|
|
64
|
+
votrix tools site env set SITE --from-file FILE|- [--target production|preview|all]
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Returns Environment update result.
|
|
68
|
+
|
|
69
|
+
### `votrix tools site domain add`
|
|
70
|
+
|
|
71
|
+
Connect a custom domain.
|
|
72
|
+
|
|
73
|
+
```text
|
|
74
|
+
votrix tools site domain add SITE DOMAIN
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
Returns Domain status and DNS information.
|
|
78
|
+
|
|
79
|
+
### `votrix tools site domain status`
|
|
80
|
+
|
|
81
|
+
Check domain status.
|
|
82
|
+
|
|
83
|
+
```text
|
|
84
|
+
votrix tools site domain status SITE DOMAIN
|
|
85
|
+
```
|
|
86
|
+
|
|
87
|
+
Returns Domain status and DNS information.
|
|
88
|
+
|
|
89
|
+
### `votrix tools site track enable`
|
|
90
|
+
|
|
91
|
+
Enable or upgrade visitor tracking.
|
|
92
|
+
|
|
93
|
+
```text
|
|
94
|
+
votrix tools site track enable SITE
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
Returns Tracking state and changed flag. A change may redeploy the live version.
|
|
98
|
+
|
|
99
|
+
### `votrix tools site track disable`
|
|
100
|
+
|
|
101
|
+
Disable visitor tracking.
|
|
102
|
+
|
|
103
|
+
```text
|
|
104
|
+
votrix tools site track disable SITE
|
|
105
|
+
```
|
|
106
|
+
|
|
107
|
+
Returns Tracking state and changed flag. A change may redeploy the live version.
|
|
108
|
+
|
|
109
|
+
### `votrix tools site track events`
|
|
110
|
+
|
|
111
|
+
Discover recorded names or group events. Defaults to 30d, grouped by name, limit 50 (max 200). Grouping by another field defaults to visit.
|
|
112
|
+
|
|
113
|
+
```text
|
|
114
|
+
votrix tools site track events SITE [--period 7d|30d|90d] [--by FIELD] [--where FIELD=VALUE[,VALUE...] ...] [--event NAME] [--search TEXT] [--limit N]
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Returns data_status and rows with visitors and event count.
|
|
118
|
+
|
|
119
|
+
### `votrix tools site track funnel`
|
|
120
|
+
|
|
121
|
+
Count distinct browsers completing 2-5 steps in order. Defaults to period 30d and window 7d. Filters and grouping apply to the first step.
|
|
122
|
+
|
|
123
|
+
```text
|
|
124
|
+
votrix tools site track funnel SITE --steps NAME,NAME[,NAME...] [--period 7d|30d|90d] [--by FIELD] [--where FIELD=VALUE[,VALUE...] ...] [--window 1h|1d|7d|30d]
|
|
125
|
+
```
|
|
126
|
+
|
|
127
|
+
Returns data_status and steps (or groups) with visitors, of_previous_percent and of_first_percent.
|
|
128
|
+
|
|
129
|
+
## Example
|
|
130
|
+
|
|
131
|
+
```bash
|
|
132
|
+
votrix tools site deploy ./website --name my-site
|
|
133
|
+
votrix tools site versions my-site
|
|
134
|
+
votrix tools site status my-site
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
Deployment returns site, version, status and deployment metadata. See [visitor analytics](../../SITE-TRACKING-CLI-DESIGN.md) for instrumentation and funnel reports.
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# Social publishing
|
|
2
|
+
|
|
3
|
+
Select a connected social account and use its account ID in a draft or scheduled post.
|
|
4
|
+
|
|
5
|
+
## Commands
|
|
6
|
+
|
|
7
|
+
### `votrix tools social accounts`
|
|
8
|
+
|
|
9
|
+
List connected social accounts.
|
|
10
|
+
|
|
11
|
+
```text
|
|
12
|
+
votrix tools social accounts [--platform NAME]
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Returns accounts array.
|
|
16
|
+
|
|
17
|
+
### `votrix tools social posts create`
|
|
18
|
+
|
|
19
|
+
Create posts from a JSON file or account and content flags.
|
|
20
|
+
|
|
21
|
+
```text
|
|
22
|
+
votrix tools social posts create [--file JSON_FILE|-] [--account ID ...] [--caption TEXT|--caption-file FILE] [--media URL|PATH|ASSET ...] [--thumbnail X] [--title TEXT] [--schedule-at TIME|--draft]
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Returns Created post records.
|
|
26
|
+
|
|
27
|
+
### `votrix tools social posts update`
|
|
28
|
+
|
|
29
|
+
Update a post.
|
|
30
|
+
|
|
31
|
+
```text
|
|
32
|
+
votrix tools social posts update ID [--file JSON_FILE|-] [--account ID ...] [--caption TEXT|--caption-file FILE] [--media URL|PATH|ASSET ...] [--thumbnail X] [--title TEXT] [--schedule-at TIME|--draft]
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Returns Updated post record.
|
|
36
|
+
|
|
37
|
+
### `votrix tools social posts list`
|
|
38
|
+
|
|
39
|
+
List posts (default limit 50, offset 0).
|
|
40
|
+
|
|
41
|
+
```text
|
|
42
|
+
votrix tools social posts list [--account ID ...] [--status STATUS ...] [--limit N] [--offset N]
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Returns Post records.
|
|
46
|
+
|
|
47
|
+
### `votrix tools social posts get`
|
|
48
|
+
|
|
49
|
+
Inspect a post.
|
|
50
|
+
|
|
51
|
+
```text
|
|
52
|
+
votrix tools social posts get ID
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Returns Post record.
|
|
56
|
+
|
|
57
|
+
### `votrix tools social posts results`
|
|
58
|
+
|
|
59
|
+
Read publication results.
|
|
60
|
+
|
|
61
|
+
```text
|
|
62
|
+
votrix tools social posts results ID
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
Returns Platform results.
|
|
66
|
+
|
|
67
|
+
### `votrix tools social posts cancel`
|
|
68
|
+
|
|
69
|
+
Cancel a post.
|
|
70
|
+
|
|
71
|
+
```text
|
|
72
|
+
votrix tools social posts cancel ID
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
Returns Cancellation result.
|
|
76
|
+
|
|
77
|
+
## Example
|
|
78
|
+
|
|
79
|
+
```bash
|
|
80
|
+
votrix tools social accounts
|
|
81
|
+
votrix tools social posts create --account ACCOUNT_ID --caption "Launch day" --draft
|
|
82
|
+
votrix tools social posts get POST_ID
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
Create returns posts with their IDs. Use results to retrieve publication outcomes.
|
package/docs/cli/ui.md
ADDED
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
# UI tools
|
|
2
|
+
|
|
3
|
+
Discover design recipes and run one with the inputs returned by explore.
|
|
4
|
+
|
|
5
|
+
## Commands
|
|
6
|
+
|
|
7
|
+
### `votrix tools ui list`
|
|
8
|
+
|
|
9
|
+
Discover available tools.
|
|
10
|
+
|
|
11
|
+
```text
|
|
12
|
+
votrix tools ui list
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Returns Current catalog.
|
|
16
|
+
|
|
17
|
+
### `votrix tools ui explore`
|
|
18
|
+
|
|
19
|
+
Inspect supported parameters, outputs and price.
|
|
20
|
+
|
|
21
|
+
```text
|
|
22
|
+
votrix tools ui explore NAME [--mode MODE]
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
Returns Tool description and parameter schema.
|
|
26
|
+
|
|
27
|
+
### `votrix tools ui run`
|
|
28
|
+
|
|
29
|
+
Run a tool. Explore its inputs first. Waits by default.
|
|
30
|
+
|
|
31
|
+
```text
|
|
32
|
+
votrix tools ui run NAME [--mode MODE] [--input JSON|@FILE] [--PARAM VALUE ...] [--max-cost USD] [--out DIR] [--no-wait]
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
Returns Run ID, status and available results or files.
|
|
36
|
+
|
|
37
|
+
## Example
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
votrix tools ui list
|
|
41
|
+
votrix tools ui explore design
|
|
42
|
+
votrix tools ui run design --site-type "bookshop" --story "choose a book" --out ./out
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
Use the files array to locate generated outputs.
|
package/package.json
CHANGED
|
@@ -1,6 +1,32 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@votrix-ai/cli",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.2.0",
|
|
4
|
+
"description": "Hand work to Votrix employees and run Votrix tools from a terminal or another agent.",
|
|
5
|
+
"license": "UNLICENSED",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"bin": {
|
|
8
|
+
"votrix": "dist/src/cli.js"
|
|
9
|
+
},
|
|
10
|
+
"files": [
|
|
11
|
+
"dist/src/*.js",
|
|
12
|
+
"production.json",
|
|
13
|
+
"skills",
|
|
14
|
+
"README.md",
|
|
15
|
+
"SITE-TRACKING-CLI-DESIGN.md",
|
|
16
|
+
"docs"
|
|
17
|
+
],
|
|
18
|
+
"engines": {
|
|
19
|
+
"node": ">=18.17"
|
|
20
|
+
},
|
|
21
|
+
"scripts": {
|
|
22
|
+
"build": "tsc -p tsconfig.json && node -e \"require('fs').chmodSync('dist/src/cli.js', 0o755)\"",
|
|
23
|
+
"test": "npm run build && node scripts/command-docs.mjs --check && node --test dist/test/*.test.js",
|
|
24
|
+
"prepare": "npm run build",
|
|
25
|
+
"prepublishOnly": "npm test",
|
|
26
|
+
"docs": "npm run build && node scripts/command-docs.mjs"
|
|
27
|
+
},
|
|
28
|
+
"devDependencies": {
|
|
29
|
+
"@types/node": "20.17.6",
|
|
30
|
+
"typescript": "5.6.3"
|
|
31
|
+
}
|
|
32
|
+
}
|
package/production.json
ADDED
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: votrix
|
|
3
|
+
description: "Use the votrix CLI to hand work to Votrix employees and collect the files they make, run Votrix tools (generate images, video and audio; SEO data; scrape social and web data; website UI designs), publish or schedule prepared social posts, and use workspace files. Use for Votrix tasks from the terminal; source-code work alone does not require this skill."
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# Votrix
|
|
7
|
+
|
|
8
|
+
Run the `votrix` command (installed with `npm install -g @votrix-ai/cli`, or `npx -y @votrix-ai/cli` in its place). Every command prints one JSON object on stdout, errors included as `{"error": {"type", "message", "fix"}}`; progress goes to stderr; nothing prompts. Exit code 0 is an answer, 1 a failure, 2 bad usage. Read `error.fix` and follow it.
|
|
9
|
+
|
|
10
|
+
## Get ready
|
|
11
|
+
|
|
12
|
+
- `votrix whoami` shows the account, workspace and key in use. If it says to log in, run `votrix login` and let the user finish Google sign-in in a browser on this computer while the command waits.
|
|
13
|
+
- `votrix login` keeps one API key per workspace for this device. A caller with only a key sets `VOTRIX_API_KEY`; it acts in that key's workspace with its scopes.
|
|
14
|
+
- With several workspaces, pass `--workspace <id>` (from `votrix workspaces`) or set a default with `votrix workspace use <id>`.
|
|
15
|
+
- Use the saved login or the given key. Keep credential files and keys out of output.
|
|
16
|
+
|
|
17
|
+
## Choose the path
|
|
18
|
+
|
|
19
|
+
- A prepared post with approved content and accounts: `votrix tools social ...`.
|
|
20
|
+
- A generated image, video, audio clip, SEO dataset, scrape, or UI design the user describes exactly: `votrix tools <category> run ...`.
|
|
21
|
+
- Work that needs an employee's judgement and skills (a campaign, a website, a researched report), or continuing an employee conversation: `votrix agent ask ...`.
|
|
22
|
+
|
|
23
|
+
## Hand work to an employee
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
votrix agent ls
|
|
27
|
+
votrix agent ask rebecca 'Make a 30-second launch video for this product' --file ./product.png --out ./votrix-out
|
|
28
|
+
votrix agent ask rebecca 'Make it vertical' --session SESSION_ID --out ./votrix-out
|
|
29
|
+
votrix agent sessions --employee rebecca
|
|
30
|
+
votrix agent get SESSION_ID
|
|
31
|
+
votrix agent files SESSION_ID
|
|
32
|
+
votrix agent pull ASSET_ID [ASSET_ID ...] --out ./votrix-out
|
|
33
|
+
votrix agent history SESSION_ID --limit 20
|
|
34
|
+
votrix agent stop SESSION_ID
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
- `ls` gives each employee's `name`, `slug` and `role`; pick the one whose role fits. `ask` takes the name, slug or id.
|
|
38
|
+
- `ask` starts a new session unless `--session` continues one, and blocks until the whole session is done, including subagents and background jobs that wake the employee again. That can take many minutes: run it in the background and read its output when it exits. Another `ask --session` while it works is queued for the employee.
|
|
39
|
+
- The result is `{"session_id", "employee", "status", "reply", "presented"}`, for this task only. `status` is `idle` (done) or `failed`. `presented` lists the files the employee handed over in this task; with `--out` each has a local `path`. A website or video project arrives as its `.zip`.
|
|
40
|
+
- `files <session>` lists every file in the session's outputs folder (`filename`, `size_bytes`, `kind`); pull any of them by asset id.
|
|
41
|
+
- `--file` takes a local path (uploaded, at most 500 MiB) or any asset id in the workspace. For a long or multiline task pass `-` as the task and give it on stdin.
|
|
42
|
+
- `sessions` finds earlier conversations; `history` returns messages oldest first and pages back with the `before` it returns.
|
|
43
|
+
- If `ask` was cut off, the employee keeps working: `get SESSION_ID` shows where it stands. Send the task once; `stop` interrupts everything the session is doing.
|
|
44
|
+
|
|
45
|
+
## Run a tool
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
votrix tools media list
|
|
49
|
+
votrix tools media explore seedance
|
|
50
|
+
votrix tools media run seedance --mode text_to_video --prompt 'A calm sea at dawn' --duration 5 --out ./votrix-out
|
|
51
|
+
votrix tools seo list
|
|
52
|
+
votrix tools seo explore keyword_metrics
|
|
53
|
+
votrix tools seo run keyword_metrics --keywords '["restaurant pos"]'
|
|
54
|
+
votrix tools scraper list
|
|
55
|
+
votrix tools scraper run reddit-communities --topic seo
|
|
56
|
+
votrix tools scraper run reddit-posts --where r/SEO --query 'new site not ranking' --limit 20
|
|
57
|
+
votrix tools ui run design --site-type 'online sneaker store' --story 'choosing a size, then adding to cart' --out ./votrix-out
|
|
58
|
+
votrix tools runs get RUN_ID --out ./votrix-out
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
- Read the catalog first: `list` shows what each category holds today and `explore <name>` its modes, parameters, price and the exact fields it returns. Models change; use the names and aliases the catalog gives (`seedance`, `video`) rather than remembered ones.
|
|
62
|
+
- Pass parameters as `--<parameter> VALUE` (JSON values are parsed; repeat a flag for a list), or all at once with `--input '{...}'` / `--input @file.json`. A local file path as a value is uploaded for you.
|
|
63
|
+
- `run` blocks until done and returns `{"run_id", "status", "result", "files", "cost_usd", "error"}`; `--out DIR` downloads `files`. `--max-cost USD` refuses a run estimated above it. Ask for the shortest video that works first: video is billed by length and resolution.
|
|
64
|
+
- Runs spend workspace credits. Run what the user asked for, once; if a run is cut off, `votrix tools runs get RUN_ID` collects it.
|
|
65
|
+
|
|
66
|
+
## Publish social posts
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
votrix tools social accounts --platform youtube
|
|
70
|
+
votrix tools social posts create --account ACCOUNT_ID --caption 'Approved content' --media ./original.mp4 --title 'Video title'
|
|
71
|
+
votrix tools social posts create --account ACCOUNT_ID --caption 'Approved content' --media ASSET_ID --schedule-at '2030-01-01T12:00:00Z'
|
|
72
|
+
votrix tools social posts create --account ACCOUNT_ID --caption-file ./caption.txt --draft
|
|
73
|
+
votrix tools social posts update POST_ID --file ./post.json
|
|
74
|
+
votrix tools social posts list --status scheduled
|
|
75
|
+
votrix tools social posts get POST_ID
|
|
76
|
+
votrix tools social posts results POST_ID
|
|
77
|
+
votrix tools social posts cancel POST_ID
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
- Use account ids from `accounts`; repeat `--account` for several accounts. Accounts with `is_active: false` need reconnecting in the App.
|
|
81
|
+
- `--media` takes a public URL, a workspace asset id, or a local path (uploaded first); repeat it for several. `--thumbnail` sets the cover of a single video; `--title` sets a YouTube title.
|
|
82
|
+
- `create` publishes immediately unless `--draft` or a future `--schedule-at` with a timezone is given. Publish only the content, accounts and timing the user approved.
|
|
83
|
+
- `--file post.json` takes the whole request: `account_ids`, `caption`, `media` (`url` or `asset_id`, optional `thumbnail_url`/`thumbnail_asset_id`), `scheduled_at`, `draft`, `platform_configurations`, `account_configurations`.
|
|
84
|
+
- `processed` does not prove delivery: check `results` and each result's `success`. After an uncertain write, read `list`/`get` before trying again.
|
|
85
|
+
|
|
86
|
+
## Workspace files
|
|
87
|
+
|
|
88
|
+
```bash
|
|
89
|
+
votrix tools files upload ./materials.zip
|
|
90
|
+
votrix tools files get ASSET_ID
|
|
91
|
+
votrix tools files pull ASSET_ID --out ./votrix-out
|
|
92
|
+
votrix tools files library --query launch
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
`upload` registers files without sending them anywhere; pass the ids to `agent ask --file` or `--media`.
|
|
96
|
+
|
|
97
|
+
This skill is shared by Codex and Claude Code. It describes how to use the CLI; it does not authorize sending work, spending credits, or publishing beyond the user's request.
|