@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/docs/API.md ADDED
@@ -0,0 +1,95 @@
1
+ # Votrix AI CLI HTTP API
2
+
3
+ Use the backend origin selected by the CLI. Send `Authorization: Bearer <credential>` and `X-Workspace-Id: <workspace UUID>` on workspace requests. A workspace API key acts within its own grant. Site operations require `tools:sites` and integrations require `tools:integrations`. Send JSON request bodies with `Content-Type: application/json`.
4
+
5
+ ## Website analytics
6
+
7
+ Deploy with `POST /tools/sites/{site}/versions` and a workspace ZIP asset ID. Tracking defaults to enabled. A track toggle takes `{"enabled":true}` or `{"enabled":false}` and returns the tracking state and whether the site changed.
8
+
9
+ Query `POST /tools/sites/{site}/track/events` with `{"period":"30d","by":"source","event":"visit"}`. Available results contain `rows` with a grouping value, distinct browser count (`visitors`), and event count (`count`).
10
+
11
+ Query `POST /tools/sites/{site}/track/funnel` with the following body. The period defaults to 30 days and the conversion window to seven days. A grouped response contains `groups`. An ungrouped response contains `steps`, each with a name, visitor count and conversion percentages.
12
+
13
+ ```json
14
+ {"steps":["visit","login","signup_completed"],"where":{"source":["utm:instagram"]},"period":"30d","window":"7d"}
15
+ ```
16
+
17
+ See [site tracking](../SITE-TRACKING-CLI-DESIGN.md) for supported values and example responses.
18
+
19
+ ## Connected applications
20
+
21
+ List workspace connections with `GET /tools/integrations`. To connect an app, post `{"app":"gmail"}` to `/tools/integrations/connect` and give the hosted URL to the user. Search for actions with `{"query":"read my Gmail profile","toolkits":["gmail"]}`. Fetch an action schema, then post `{"arguments":{}}` to its validate or execute endpoint. Select an account with the optional `account` ID. Execution returns `ok` plus `data` or an error. A completed HTTP request can still return `ok: false`. See [connected apps](cli/integrations.md).
22
+
23
+ ## Endpoint reference
24
+
25
+ Path placeholders appear in braces. Required body fields end with an asterisk. Query parameters are optional unless marked. Where a request uses SSE, the response is an event stream. For signed file uploads, request a ticket, PUT the file bytes to its URL and then register the object. CLI login uses Google via Supabase PKCE before minting workspace device keys.
26
+
27
+ ### Account, sessions and files
28
+
29
+ | Method and path | Operation | Query parameters | JSON input fields |
30
+ | --- | --- | --- | --- |
31
+ | `GET /employees` | List Employees | — | — |
32
+ | `POST /employees` | Hire Employee | — | `agent_blueprint_id*` |
33
+ | `POST /sessions/create` | Create Session Endpoint | — | `is_main`, `employee_id*`, `model`, `initial_message` |
34
+ | `GET /sessions/list` | List Sessions | `employee_id`, `limit`, `before` | — |
35
+ | `GET /sessions/{session_id}/status` | Get Session Status | — | — |
36
+ | `GET /sessions/{session_id}/events/list` | List Session Events | `before`, `after`, `limit` | — |
37
+ | `POST /sessions/{session_id}/events/send` | Send Session Event | — | JSON object |
38
+ | `GET /sessions/{session_id}/events/stream` | Stream Session Events | `after_seq` | — |
39
+ | `GET /sessions/{session_id}/files/list` | List Session Assets | — | — |
40
+ | `GET /workspaces` | List Workspaces | — | — |
41
+ | `POST /workspaces` | Create Workspace | — | `display_name*` |
42
+ | `POST /workspaces/{workspace_id}/api-keys` | Create Api Key | — | `name*`, `kind`, `scopes`, `device_id`, `expires_in_days` |
43
+ | `GET /workspaces/{workspace_id}/api-keys` | List Api Keys | — | — |
44
+ | `GET /users/me` | Get Me | — | — |
45
+ | `PATCH /users/me` | Update Me | — | `display_name*` |
46
+ | `GET /api-keys/current` | Current Api Key | — | — |
47
+ | `DELETE /api-keys/current` | Revoke Current Api Key | — | — |
48
+ | `GET /billing/balance` | Read Balance | — | — |
49
+ | `POST /files/upload-url` | Create Upload Url | — | `filename`, `mime_type`, `size_bytes` |
50
+ | `POST /files/register` | Register Upload | — | `storage_key*`, `filename`, `mime_type` |
51
+ | `GET /files/save/list` | List Library | `mime_group`, `employee_id`, `q`, `limit`, `before` | — |
52
+ | `GET /files/{file_id}` | Get File | — | — |
53
+ | `DELETE /files/{file_id}` | Delete File | — | — |
54
+ | `GET /files/{file_id}/download` | Download File | — | — |
55
+ | `POST /files/{file_id}/publish` | Publish File | — | `name*` |
56
+
57
+ ### Tools
58
+
59
+ | Method and path | Operation | Query parameters | JSON input fields |
60
+ | --- | --- | --- | --- |
61
+ | `GET /tools/social/accounts` | Accounts | — | — |
62
+ | `POST /tools/social/posts` | Create Post | — | `account_ids*`, `caption`, `media`, `scheduled_at`, `draft`, `platform_configurations`, `account_configurations` |
63
+ | `GET /tools/social/posts` | List Posts | `account_id`, `status`, `limit`, `offset` | — |
64
+ | `GET /tools/social/posts/{post_id}` | Get Post | — | — |
65
+ | `PUT /tools/social/posts/{post_id}` | Update Post | — | `account_ids*`, `caption`, `media`, `scheduled_at`, `draft`, `platform_configurations`, `account_configurations` |
66
+ | `DELETE /tools/social/posts/{post_id}` | Cancel Post | — | — |
67
+ | `GET /tools/social/posts/{post_id}/results` | Post Results | `limit`, `offset` | — |
68
+ | `GET /tools/sites` | List Sites | — | — |
69
+ | `POST /tools/sites/{site}/versions` | Deploy | — | `asset_id*`, `address`, `track` |
70
+ | `GET /tools/sites/{site}/versions` | Versions | — | — |
71
+ | `GET /tools/sites/{site}/status` | Status | `version`, `logs` | — |
72
+ | `POST /tools/sites/{site}/live` | Put Back | — | `version*` |
73
+ | `GET /tools/sites/{site}/env` | Env List | — | — |
74
+ | `PUT /tools/sites/{site}/env` | Env Set | — | `variables*`, `target` |
75
+ | `POST /tools/sites/{site}/domains` | Domain Add | — | `domain*` |
76
+ | `GET /tools/sites/{site}/domains/{domain}` | Domain Status | — | — |
77
+ | `POST /tools/sites/{site}/track` | Set Tracking | — | `enabled*` |
78
+ | `POST /tools/sites/{site}/track/events` | Track Events | — | `period`, `by`, `event`, `where`, `search`, `limit` |
79
+ | `POST /tools/sites/{site}/track/funnel` | Track Funnel | — | `steps*`, `period`, `window`, `where`, `by` |
80
+ | `GET /tools/integrations` | Connections | `toolkit` | — |
81
+ | `POST /tools/integrations/connect` | Connect | — | `app*` |
82
+ | `POST /tools/integrations/search` | Search | — | `query*`, `toolkits`, `limit` |
83
+ | `GET /tools/integrations/actions/{action}/schema` | Schema | — | — |
84
+ | `POST /tools/integrations/actions/{action}/validate` | Validate | — | `arguments`, `account` |
85
+ | `POST /tools/integrations/actions/{action}/execute` | Execute | — | `arguments`, `account` |
86
+ | `GET /tools/runs` | List Runs | `category`, `limit` | — |
87
+ | `GET /tools/runs/{run_id}` | Get Run | `wait` | — |
88
+ | `DELETE /tools/runs/{run_id}` | Cancel Run | — | — |
89
+ | `GET /tools/{category}` | Catalog | — | — |
90
+ | `GET /tools/{category}/{name}` | Explore | `mode` | — |
91
+ | `POST /tools/{category}/{name}/runs` | Create Run | — | `mode`, `input`, `max_cost_usd` |
92
+
93
+ ## Errors
94
+
95
+ The HTTP status distinguishes invalid input, missing credentials, insufficient scope, missing resources and conflicts. Site and integration routes can provide structured `detail.type`, `detail.message`, and a suggested `detail.fix`. A POST to an execute endpoint can change provider data. After a timeout, inspect the provider before retrying.
@@ -0,0 +1,76 @@
1
+ # Account and workspace
2
+
3
+ Select the workspace used for subsequent requests. Login stores one device key per workspace.
4
+
5
+ ## Commands
6
+
7
+ ### `votrix login`
8
+
9
+ Sign in to Votrix with Google (default port 8765, timeout 180 seconds).
10
+
11
+ ```text
12
+ votrix login [--no-browser] [--port N] [--timeout S]
13
+ ```
14
+
15
+ Returns Device credentials for the account's workspaces.
16
+
17
+ ### `votrix logout`
18
+
19
+ Revoke the saved device keys.
20
+
21
+ ```text
22
+ votrix logout
23
+ ```
24
+
25
+ Returns Logout result.
26
+
27
+ ### `votrix whoami`
28
+
29
+ Show the current identity and workspace.
30
+
31
+ ```text
32
+ votrix whoami
33
+ ```
34
+
35
+ Returns Account and credential metadata.
36
+
37
+ ### `votrix workspaces`
38
+
39
+ List available workspaces.
40
+
41
+ ```text
42
+ votrix workspaces
43
+ ```
44
+
45
+ Returns workspaces array.
46
+
47
+ ### `votrix workspace use`
48
+
49
+ Select a workspace by ID.
50
+
51
+ ```text
52
+ votrix workspace use ID
53
+ ```
54
+
55
+ Returns workspace_id.
56
+
57
+ ### `votrix credits`
58
+
59
+ Check workspace credit usage.
60
+
61
+ ```text
62
+ votrix credits
63
+ ```
64
+
65
+ Returns balance and recent charges.
66
+
67
+ ## Example
68
+
69
+ ```bash
70
+ votrix workspaces
71
+ votrix workspace use WORKSPACE_ID
72
+ votrix whoami
73
+ votrix credits
74
+ ```
75
+
76
+ Workspace selection returns workspace_id. Credits returns the balance and recent ledger entries.
@@ -0,0 +1,105 @@
1
+ # Employees and sessions
2
+
3
+ Start a task with an employee slug or ID. Use a session ID to resume or inspect prior work.
4
+
5
+ ## Commands
6
+
7
+ ### `votrix agent ls`
8
+
9
+ List available employees.
10
+
11
+ ```text
12
+ votrix agent ls
13
+ ```
14
+
15
+ Returns Employee identifiers and roles.
16
+
17
+ ### `votrix agent ask`
18
+
19
+ Send a task and wait by default.
20
+
21
+ ```text
22
+ votrix agent ask EMPLOYEE TASK|- [--file PATH|ID ...] [--session ID] [--out DIR] [--no-wait]
23
+ ```
24
+
25
+ Returns Session ID and, after completion, reply and presented files.
26
+
27
+ ### `votrix agent wait`
28
+
29
+ Wait for the latest task.
30
+
31
+ ```text
32
+ votrix agent wait SESSION [--out DIR]
33
+ ```
34
+
35
+ Returns Session status, reply and presented files.
36
+
37
+ ### `votrix agent sessions`
38
+
39
+ List recent conversations.
40
+
41
+ ```text
42
+ votrix agent sessions [--employee NAME] [--limit N] [--before UPDATED_AT]
43
+ ```
44
+
45
+ Returns Session records.
46
+
47
+ ### `votrix agent get`
48
+
49
+ Inspect a session without waiting.
50
+
51
+ ```text
52
+ votrix agent get SESSION
53
+ ```
54
+
55
+ Returns Session status.
56
+
57
+ ### `votrix agent files`
58
+
59
+ List output files.
60
+
61
+ ```text
62
+ votrix agent files SESSION
63
+ ```
64
+
65
+ Returns File metadata.
66
+
67
+ ### `votrix agent pull`
68
+
69
+ Download output assets.
70
+
71
+ ```text
72
+ votrix agent pull ASSET ... [--out DIR]
73
+ ```
74
+
75
+ Returns Downloaded files and paths.
76
+
77
+ ### `votrix agent history`
78
+
79
+ Read messages and presented files.
80
+
81
+ ```text
82
+ votrix agent history SESSION [--limit N] [--before SEQ]
83
+ ```
84
+
85
+ Returns History rows and pagination.
86
+
87
+ ### `votrix agent stop`
88
+
89
+ Interrupt a running session.
90
+
91
+ ```text
92
+ votrix agent stop SESSION
93
+ ```
94
+
95
+ Returns Session and interruption result.
96
+
97
+ ## Example
98
+
99
+ ```bash
100
+ votrix agent ls
101
+ votrix agent ask rebecca "Review the attached brief" --file brief.pdf --no-wait
102
+ votrix agent wait SESSION_ID --out ./results
103
+ ```
104
+
105
+ A completed task returns session_id, status, reply and presented files.
@@ -0,0 +1,65 @@
1
+ # Workspace files
2
+
3
+ Upload files, inspect metadata, download assets, or publish an asset at a public URL.
4
+
5
+ ## Commands
6
+
7
+ ### `votrix tools files upload`
8
+
9
+ Upload local files privately.
10
+
11
+ ```text
12
+ votrix tools files upload PATH ...
13
+ ```
14
+
15
+ Returns Asset IDs and file metadata.
16
+
17
+ ### `votrix tools files get`
18
+
19
+ Inspect file metadata.
20
+
21
+ ```text
22
+ votrix tools files get ASSET
23
+ ```
24
+
25
+ Returns File record.
26
+
27
+ ### `votrix tools files pull`
28
+
29
+ Download workspace assets.
30
+
31
+ ```text
32
+ votrix tools files pull ASSET ... [--out DIR]
33
+ ```
34
+
35
+ Returns Local paths.
36
+
37
+ ### `votrix tools files publish`
38
+
39
+ Publish a file at a permanent public URL.
40
+
41
+ ```text
42
+ votrix tools files publish ASSET|PATH --name NAME
43
+ ```
44
+
45
+ Returns Publication information.
46
+
47
+ ### `votrix tools files library`
48
+
49
+ Search saved workspace files. Default limit 50.
50
+
51
+ ```text
52
+ votrix tools files library [--query TEXT] [--mime-group GROUP ...] [--before CURSOR] [--limit N]
53
+ ```
54
+
55
+ Returns Matching file records.
56
+
57
+ ## Example
58
+
59
+ ```bash
60
+ votrix tools files upload ./brief.pdf
61
+ votrix tools files get ASSET_ID
62
+ votrix tools files pull ASSET_ID --out ./out
63
+ ```
64
+
65
+ Upload returns files and their asset IDs. Publish makes the selected file publicly accessible.
@@ -0,0 +1,67 @@
1
+ # Connected applications
2
+
3
+ Discover toolkit slugs, link an account, search for an action, inspect its schema and execute with JSON arguments.
4
+
5
+ ## Commands
6
+
7
+ ### `votrix tools integrations toolkits list`
8
+
9
+ List supported apps offline.
10
+
11
+ ```text
12
+ votrix tools integrations toolkits list
13
+ ```
14
+
15
+ Returns toolkits with name and slug.
16
+
17
+ ### `votrix tools integrations connections list`
18
+
19
+ List workspace connections.
20
+
21
+ ```text
22
+ votrix tools integrations connections list [--toolkit APP]
23
+ ```
24
+
25
+ Returns apps with accounts and status.
26
+
27
+ ### `votrix tools integrations link`
28
+
29
+ Request the hosted OAuth URL. Open the returned URL to authorize.
30
+
31
+ ```text
32
+ votrix tools integrations link APP [--no-browser] [--no-wait]
33
+ ```
34
+
35
+ Returns app, url, status, account_id and expires_at.
36
+
37
+ ### `votrix tools integrations search`
38
+
39
+ Search the live action catalog. Default limit 20.
40
+
41
+ ```text
42
+ votrix tools integrations search QUERY [--toolkits APP,APP] [--limit N]
43
+ ```
44
+
45
+ Returns actions and needs_connection.
46
+
47
+ ### `votrix tools integrations execute`
48
+
49
+ Inspect the live schema, validate arguments or execute the action. Data defaults to {}.
50
+
51
+ ```text
52
+ votrix tools integrations execute ACTION --get-schema
53
+ votrix tools integrations execute ACTION [-d|--data JSON|@FILE|-] [--account ID] [--dry-run]
54
+ ```
55
+
56
+ Returns Schema mode returns input_schema and output_schema. Dry-run returns valid. Execution returns ok, action and data or error.
57
+
58
+ ## Example
59
+
60
+ ```bash
61
+ votrix tools integrations toolkits list
62
+ votrix tools integrations connections list --toolkit gmail
63
+ votrix tools integrations execute GMAIL_GET_PROFILE --get-schema
64
+ votrix tools integrations execute GMAIL_GET_PROFILE -d '{}'
65
+ ```
66
+
67
+ Link returns a hosted OAuth URL. Execute returns ok, action and data or an error. Supply --account ID if the workspace has several active connections for that toolkit.
@@ -0,0 +1,45 @@
1
+ # Media tools
2
+
3
+ Discover models, their modes and the parameters accepted by each.
4
+
5
+ ## Commands
6
+
7
+ ### `votrix tools media list`
8
+
9
+ Discover available tools.
10
+
11
+ ```text
12
+ votrix tools media list
13
+ ```
14
+
15
+ Returns Current catalog.
16
+
17
+ ### `votrix tools media explore`
18
+
19
+ Inspect supported parameters, outputs and price.
20
+
21
+ ```text
22
+ votrix tools media explore NAME [--mode MODE]
23
+ ```
24
+
25
+ Returns Tool description and parameter schema.
26
+
27
+ ### `votrix tools media run`
28
+
29
+ Run a tool. Explore its inputs first. Waits by default.
30
+
31
+ ```text
32
+ votrix tools media 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 media list
41
+ votrix tools media explore seedance
42
+ votrix tools media run seedance --mode text_to_video --prompt "A calm sea at dawn" --out ./out
43
+ ```
44
+
45
+ The run result includes status, run_id and any generated files.
@@ -0,0 +1,44 @@
1
+ # Tool runs
2
+
3
+ Use the run ID returned by a category command to inspect, wait for, or stop execution.
4
+
5
+ ## Commands
6
+
7
+ ### `votrix tools runs list`
8
+
9
+ List recent runs (default limit 20).
10
+
11
+ ```text
12
+ votrix tools runs list [--category NAME] [--limit N]
13
+ ```
14
+
15
+ Returns Run records.
16
+
17
+ ### `votrix tools runs get`
18
+
19
+ Wait for a run or return its current state.
20
+
21
+ ```text
22
+ votrix tools runs get ID [--out DIR] [--no-wait]
23
+ ```
24
+
25
+ Returns Run status and available outputs.
26
+
27
+ ### `votrix tools runs stop`
28
+
29
+ Stop a run.
30
+
31
+ ```text
32
+ votrix tools runs stop ID
33
+ ```
34
+
35
+ Returns Run status.
36
+
37
+ ## Example
38
+
39
+ ```bash
40
+ votrix tools runs list --category media
41
+ votrix tools runs get RUN_ID --no-wait
42
+ ```
43
+
44
+ Get returns the current run. By default it waits for completion and --out downloads output files.
@@ -0,0 +1,45 @@
1
+ # Scraper tools
2
+
3
+ Choose a source and inspect its input and response fields.
4
+
5
+ ## Commands
6
+
7
+ ### `votrix tools scraper list`
8
+
9
+ Discover available tools.
10
+
11
+ ```text
12
+ votrix tools scraper list
13
+ ```
14
+
15
+ Returns Current catalog.
16
+
17
+ ### `votrix tools scraper explore`
18
+
19
+ Inspect supported parameters, outputs and price.
20
+
21
+ ```text
22
+ votrix tools scraper explore NAME [--mode MODE]
23
+ ```
24
+
25
+ Returns Tool description and parameter schema.
26
+
27
+ ### `votrix tools scraper run`
28
+
29
+ Run a tool. Explore its inputs first. Waits by default.
30
+
31
+ ```text
32
+ votrix tools scraper 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 scraper list
41
+ votrix tools scraper explore reddit-posts
42
+ votrix tools scraper run reddit-posts --where r/SEO --query "site ranking" --limit 20
43
+ ```
44
+
45
+ The run returns its status and source-specific results.
@@ -0,0 +1,45 @@
1
+ # SEO tools
2
+
3
+ Inspect a dataset before supplying keywords or domains.
4
+
5
+ ## Commands
6
+
7
+ ### `votrix tools seo list`
8
+
9
+ Discover available tools.
10
+
11
+ ```text
12
+ votrix tools seo list
13
+ ```
14
+
15
+ Returns Current catalog.
16
+
17
+ ### `votrix tools seo explore`
18
+
19
+ Inspect supported parameters, outputs and price.
20
+
21
+ ```text
22
+ votrix tools seo explore NAME [--mode MODE]
23
+ ```
24
+
25
+ Returns Tool description and parameter schema.
26
+
27
+ ### `votrix tools seo run`
28
+
29
+ Run a tool. Explore its inputs first. Waits by default.
30
+
31
+ ```text
32
+ votrix tools seo 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 seo list
41
+ votrix tools seo explore keyword_metrics
42
+ votrix tools seo run keyword_metrics --keywords '["restaurant pos"]'
43
+ ```
44
+
45
+ Read the returns schema from explore for the fields in each result row.