openmates 0.14.1-alpha.0 → 0.14.3-alpha.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.
Files changed (2) hide show
  1. package/README.md +257 -34
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,65 +1,282 @@
1
1
  # openmates
2
2
 
3
- Terminal CLI and Node.js SDK for OpenMates. Use it to pair-login, create or continue encrypted chats, run app skills, manage safe account settings, browse docs, and administer self-hosted installs.
3
+ <img src="https://openmates.org/favicon.png" alt="OpenMates" width="72">
4
+
5
+ Terminal CLI for OpenMates. Use it to chat from your shell, run app skills,
6
+ inspect encrypted account data, export chats, browse docs, and install or manage
7
+ self-hosted OpenMates servers.
8
+
9
+ [OpenMates](https://openmates.org) | [CLI docs](https://openmates.org/docs/user-guide/cli) | [Self-hosting docs](https://openmates.org/docs/self-hosting/setup) | [Source](https://github.com/glowingkitty/OpenMates/tree/dev/frontend/packages/openmates-cli)
4
10
 
5
11
  ## Install
6
12
 
7
13
  ```bash
8
14
  npm install -g openmates
15
+ ```
16
+
17
+ Requires Node.js 20 or newer.
18
+
19
+ Install the latest dev prerelease:
20
+
21
+ ```bash
22
+ npm install -g openmates@alpha
23
+ ```
24
+
25
+ Update an existing global install:
26
+
27
+ ```bash
28
+ openmates update
29
+ openmates update --dry-run
30
+ openmates update --version alpha
31
+ ```
32
+
33
+ ## Quick Start
34
+
35
+ Run the interactive terminal chat UI:
36
+
37
+ ```bash
9
38
  openmates
39
+ ```
40
+
41
+ In the TUI, use `/help`, `/examples`, `/login`, `/signup`, and `/exit`.
42
+ When stdin or stdout is redirected, plain `openmates` prints a script-friendly
43
+ quickstart instead of opening the TUI.
44
+
45
+ Login with pair-auth:
46
+
47
+ ```bash
10
48
  openmates login
49
+ openmates whoami --json
50
+ ```
51
+
52
+ The CLI displays a QR code or pair PIN. Approve it in the OpenMates web app.
53
+ During login, the CLI never asks for your account password.
54
+
55
+ Create a new account from the terminal:
56
+
57
+ ```bash
58
+ openmates signup
11
59
  ```
12
60
 
13
- Run plain `openmates` in an interactive terminal to open the full-screen chat UI. Use `/examples` to browse public example chats, type into any example to continue it as a new real or anonymous chat, `/login` for pair-auth, `/signup` for guided account creation, and `/embed <id>` to jump to full embed details. If stdin or stdout is redirected, plain `openmates` prints a script-friendly quickstart instead of entering the TUI.
61
+ Signup collects passwords, 2FA codes, backup codes, and recovery keys through
62
+ hidden prompts or owner-only files, not command-line password flags.
14
63
 
15
- Without a session, `openmates chats list`, `show`, and `open` display clearly labeled public example chats from the web app. Login uses pair-auth: the CLI shows a QR code or PIN, and you approve it in the web app. To create a new account from the terminal, run `openmates signup`; passwords and recovery secrets are collected through hidden prompts, never command-line flags.
64
+ ## Common Commands
16
65
 
17
- ## First Commands
66
+ ### Chat from the shell
18
67
 
19
68
  ```bash
20
- openmates whoami --json
21
69
  openmates chats list
22
- openmates chats show example-gigantic-airplanes
70
+ openmates chats show last
23
71
  openmates chats new "Help me plan my day"
24
- openmates chats new "Review @./src/app.ts"
25
72
  openmates chats send --chat <chat-id> "continue"
26
- openmates embeds show <embed-id>
73
+ openmates chats incognito "Answer without saving this chat"
74
+ ```
75
+
76
+ Without login, `openmates chats list`, `show`, and `open` display clearly labeled
77
+ public example chats from the web app.
78
+
79
+ ### Attach local files and mentions
80
+
81
+ ```bash
82
+ openmates chats new "@Sophia review @./src/app.ts"
83
+ openmates chats new "@Best summarize @./notes.md"
84
+ openmates mentions list
85
+ ```
86
+
87
+ The CLI redacts likely secrets before sending file content. Private keys and
88
+ high-risk files are blocked by default.
89
+
90
+ ### Export, share, and delete chats
91
+
92
+ ```bash
93
+ openmates chats download last --output ~/exports
94
+ openmates chats download <chat-id> --zip
95
+ openmates chats share last --expires 604800
96
+ openmates chats delete <chat-id> --yes
97
+ ```
98
+
99
+ Exports include YAML and Markdown. When present, code embeds and video
100
+ transcripts are written as separate files.
101
+
102
+ ### Run app skills
103
+
104
+ ```bash
27
105
  openmates apps list
106
+ openmates apps web search "latest AI news"
28
107
  openmates apps ai ask "What is Docker?"
29
- openmates apps code run --language python --code 'print("Hello")'
108
+ openmates apps code run --language python --code 'print("Hello from CLI")'
109
+ openmates apps travel search_connections --input '{"requests":[{"legs":[{"origin":"BER","destination":"LHR","date":"2026-04-15"}]}]}'
110
+ ```
111
+
112
+ App commands use your logged-in session by default. For non-interactive scripts,
113
+ create an API key in **Settings > Developers > API Keys**, then pass
114
+ `--api-key <key>` or set `OPENMATES_API_KEY`.
115
+
116
+ ### Account settings and data
117
+
118
+ ```bash
119
+ openmates settings --help
30
120
  openmates settings account export data --json
31
- openmates learning-mode status --json
32
121
  openmates settings memories list --json
122
+ openmates learning-mode status --json
123
+ openmates docs search "API keys"
124
+ ```
125
+
126
+ Predefined settings commands are supported. Raw settings path passthrough is not
127
+ available. Security-sensitive actions such as passkey management, password
128
+ changes, API key creation, device approvals, and card checkout stay in the web
129
+ app. The code-level guard is `BLOCKED_SETTINGS_MUTATE_PATHS` in `src/client.ts`.
130
+
131
+ ### Embeds, docs, and benchmarks
132
+
133
+ ```bash
134
+ openmates embeds show <embed-id>
135
+ openmates embeds share <embed-id> --expires 604800
33
136
  openmates docs list
34
- openmates remote-access start --path ./my-repo --source-id repo-1 --local-only
137
+ openmates docs download cli/server-management
35
138
  openmates benchmark model google/gemini-3.5-flash --dry-run --json
139
+ ```
140
+
141
+ Benchmark commands run real product-path model calls when not in `--dry-run`, so
142
+ review the spend confirmation before live runs.
143
+
144
+ ### Local source bridge
145
+
146
+ ```bash
147
+ openmates remote-access start --path ./my-repo --source-id repo-1 --local-only
148
+ openmates remote-access status --json
149
+ openmates remote-access search --source repo-1 "TODO" --limit 20
150
+ ```
151
+
152
+ `openmates remote-access` stores source metadata under
153
+ `~/.openmates/remote-sources.json`, searches with `rg` inside the approved root,
154
+ and does not upload repository files by default.
155
+
156
+ ## Self-Host Server Management
157
+
158
+ The CLI can install and manage a self-hosted OpenMates server. Server commands do
159
+ not require an OpenMates cloud login. They operate on the local Docker Compose
160
+ runtime.
161
+
162
+ ### Install a server
163
+
164
+ ```bash
36
165
  openmates server install
166
+ openmates server start
167
+ openmates server status
168
+ ```
169
+
170
+ The default install path is `~/openmates`. Use `--path <folder>` only when you
171
+ want to install somewhere else:
172
+
173
+ ```bash
174
+ openmates server install --path /opt/openmates
175
+ openmates server start --path /opt/openmates
176
+ ```
177
+
178
+ Default installs use prebuilt GHCR images and do not require Git, a source
179
+ checkout, or cloud-only deployment flags. The installer writes a runtime
180
+ directory, creates `.env`, generates local secrets, saves the self-host API
181
+ target in `~/.openmates/server.json`, and prints the first invite code.
182
+
183
+ After startup, open:
184
+
185
+ | Service | URL |
186
+ | --- | --- |
187
+ | Web app | `http://localhost:5173` |
188
+ | Backend API | `http://localhost:8000` |
189
+
190
+ The first invite creates a normal user. Promote your account separately:
191
+
192
+ ```bash
193
+ openmates server make-admin your@email.com
194
+ ```
195
+
196
+ ### Add AI providers or local models
197
+
198
+ A fresh self-hosted server can start without provider keys, but AI chat and model
199
+ processing stay unavailable until at least one real model provider is configured.
200
+
201
+ Edit `~/openmates/.env` and add a provider key, then restart:
202
+
203
+ ```env
204
+ SECRET__OPENAI__API_KEY=sk-...
205
+ SECRET__ANTHROPIC__API_KEY=sk-ant-...
206
+ SECRET__GOOGLE_AI_STUDIO__API_KEY=...
37
207
  ```
38
208
 
39
- Run `openmates --help` or `openmates <command> --help` for the full command surface. Benchmark commands also support `openmates benchmark --help` for suite, comparison, judge, and spend-confirmation options.
209
+ ```bash
210
+ openmates server restart
211
+ ```
40
212
 
41
- ## Environments
213
+ Or add a local OpenAI-compatible model served by Ollama, LM Studio, or another
214
+ runtime:
42
215
 
43
- The CLI derives the web app URL from the API URL so pair-auth lands on the matching backend.
216
+ ```bash
217
+ openmates server ai models add
218
+ openmates server ai models list
219
+ openmates server ai models test alibaba/qwen3-8b-local
220
+ ```
221
+
222
+ ### Operate and update a server
223
+
224
+ ```bash
225
+ openmates server logs --tail 200
226
+ openmates server logs --container api --follow
227
+ openmates server update --dry-run
228
+ openmates server update
229
+ openmates server backup
230
+ openmates server stop
231
+ ```
232
+
233
+ Updates pull the matching prebuilt images, restart containers, and wait for
234
+ health checks. Before replacing data-bearing services, the CLI creates a
235
+ rotating pre-update backup.
236
+
237
+ Run `openmates server --help` or read the self-hosting docs for advanced server
238
+ operations beyond the default install/start/update flow.
239
+
240
+ ## Targets and Environment Variables
241
+
242
+ The CLI derives the web app URL from the API URL so pair-auth opens the matching
243
+ environment.
44
244
 
45
245
  | Target | Command prefix |
46
246
  | --- | --- |
47
- | Production | _(none)_ |
247
+ | OpenMates cloud | none |
48
248
  | Dev server | `OPENMATES_API_URL=https://api.dev.openmates.org` |
49
- | Installed self-hosted server | _(none after `openmates server install`)_ |
249
+ | Installed self-hosted server | none after `openmates server install` |
50
250
  | Remote self-hosted server | `OPENMATES_API_URL=https://api.example.com` |
51
251
 
52
- After `openmates server install`, fresh CLI commands default to that self-hosted server (`http://localhost:8000`) unless you already have a saved login session, set `OPENMATES_API_URL`, or pass `--api-url <url>`. App-skill execution can use your logged-in session, `--api-key <key>`, or `OPENMATES_API_KEY`.
252
+ Useful variables:
53
253
 
54
- ## Safety Limits
254
+ | Variable | Purpose |
255
+ | --- | --- |
256
+ | `OPENMATES_API_URL` | Override the API endpoint. |
257
+ | `OPENMATES_APP_URL` | Override the derived web app URL for pair-auth. |
258
+ | `OPENMATES_API_KEY` | API key for app-skill and SDK calls. |
55
259
 
56
- Predefined settings commands are supported; raw `settings get/post/patch/delete` passthrough is intentionally unavailable. High-risk or browser-only flows such as passkey management, password changes, API key creation, device approvals, and card checkout stay in the web app. The code-level guard is `BLOCKED_SETTINGS_MUTATE_PATHS` in `src/client.ts`.
260
+ You can also pass `--api-url <url>`, `--api-key <key>`, and `--json` to most
261
+ commands.
57
262
 
58
- `openmates remote-access` is a local Project source bridge. It stores source metadata under `~/.openmates/remote-sources.json`, searches with `rg` inside the approved source root, and does not upload repository files by default.
263
+ ## Local Files
59
264
 
60
- ## SDK
265
+ The CLI stores local state under `~/.openmates/` with owner-only permissions.
61
266
 
62
- The package also exports a lazy API-key SDK. Create an API key in OpenMates under Settings > Developers > API Keys, then set `OPENMATES_API_KEY` or pass `apiKey` explicitly. New SDK devices must be approved in Settings > Developers > Devices before API-key calls are allowed.
267
+ | File | Purpose |
268
+ | --- | --- |
269
+ | `session.json` | Pair-auth CLI session. |
270
+ | `sync_cache.json` | Cached decrypted account data for CLI use. |
271
+ | `server.json` | Self-host install path and local API target. |
272
+ | `remote-sources.json` | Local source bridge metadata. |
273
+
274
+ Treat these files like account credentials.
275
+
276
+ ## Node.js SDK
277
+
278
+ The npm package also exports an API-key SDK for Node.js. Use it when you want a
279
+ programmatic client instead of shell commands.
63
280
 
64
281
  ```ts
65
282
  import { OpenMates } from "openmates";
@@ -69,23 +286,29 @@ const om = new OpenMates({ apiKey: process.env.OPENMATES_API_KEY });
69
286
  const search = await om.apps.web.search({
70
287
  requests: [{ query: "OpenMates SDK examples" }],
71
288
  });
289
+
290
+ const response = await om.chats.send("Summarize this release note draft.");
72
291
  ```
73
292
 
74
- SDK methods authenticate lazily; there is no `connect()` call.
293
+ SDK chats are non-persistent by default. Use `saveToAccount: true` only when you
294
+ intentionally want the chat saved to the OpenMates account.
75
295
 
76
- ```ts
77
- const latestChats = await om.chats.list(); // defaults to 10
78
- const allChats = await om.chats.list({ limit: 0 });
296
+ ## Versioning
79
297
 
80
- await om.chats.send("Summarize this release note draft.");
298
+ OpenMates shows the short product line, for example `v0.14`, in the web app.
299
+ The npm package uses exact artifact versions:
81
300
 
82
- await om.chats.send("Create a project kickoff checklist.", { saveToAccount: true });
301
+ - `0.14.N-alpha.0` is a prerelease from the `dev` branch published under the
302
+ `alpha` npm tag.
303
+ - `0.14.N` is a stable release from `main` published under the `latest` npm tag.
83
304
 
84
- await om.billing.overview();
85
- await om.billing.invoices();
86
- await om.docs.search("api keys");
87
- ```
305
+ Install stable releases with `npm install -g openmates`. Install prereleases with
306
+ `npm install -g openmates@alpha`.
88
307
 
89
- New SDK chats are non-persistent by default. Use `saveToAccount: true` only when you intentionally want the chat saved to the OpenMates account.
308
+ ## More Documentation
90
309
 
91
- Source docs: `docs/user-guide/developers/sdk.md` in the OpenMates repository.
310
+ - [CLI guide](https://openmates.org/docs/user-guide/cli)
311
+ - [Self-hosting setup](https://openmates.org/docs/self-hosting/setup)
312
+ - [SDK guide](https://openmates.org/docs/user-guide/developers/sdk)
313
+ - [Source code](https://github.com/glowingkitty/OpenMates/tree/dev/frontend/packages/openmates-cli)
314
+ - [Issue tracker](https://github.com/glowingkitty/OpenMates/issues)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "openmates",
3
- "version": "0.14.1-alpha.0",
3
+ "version": "0.14.3-alpha.0",
4
4
  "description": "OpenMates CLI and SDK",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",