openmates 0.14.1-alpha.0 → 0.14.2-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 +264 -35
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,65 +1,288 @@
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
36
- openmates server install
37
139
  ```
38
140
 
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.
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
165
+ openmates server install --path ~/openmates
166
+ openmates server install --role core --profile production --path ~/openmates
167
+ openmates server start --path ~/openmates
168
+ openmates server status --path ~/openmates
169
+ ```
170
+
171
+ Default installs use prebuilt GHCR images and do not require Git or a source
172
+ checkout. The installer writes a runtime directory, creates `.env`, generates
173
+ local secrets, saves the self-host API target in `~/.openmates/server.json`, and
174
+ prints the first invite code.
175
+
176
+ After startup, open:
177
+
178
+ | Service | URL |
179
+ | --- | --- |
180
+ | Web app | `http://localhost:5173` |
181
+ | Backend API | `http://localhost:8000` |
182
+
183
+ The first invite creates a normal user. Promote your account separately:
184
+
185
+ ```bash
186
+ openmates server make-admin your@email.com --path ~/openmates
187
+ ```
188
+
189
+ ### Add AI providers or local models
190
+
191
+ A fresh self-hosted server can start without provider keys, but AI chat and model
192
+ processing stay unavailable until at least one real model provider is configured.
193
+
194
+ Edit `~/openmates/.env` and add a provider key, then restart:
195
+
196
+ ```env
197
+ SECRET__OPENAI__API_KEY=sk-...
198
+ SECRET__ANTHROPIC__API_KEY=sk-ant-...
199
+ SECRET__GOOGLE_AI_STUDIO__API_KEY=...
200
+ ```
201
+
202
+ ```bash
203
+ openmates server restart --path ~/openmates
204
+ ```
205
+
206
+ Or add a local OpenAI-compatible model served by Ollama, LM Studio, or another
207
+ runtime:
208
+
209
+ ```bash
210
+ openmates server ai models add
211
+ openmates server ai models list
212
+ openmates server ai models test alibaba/qwen3-8b-local
213
+ ```
214
+
215
+ ### Operate and update a server
40
216
 
41
- ## Environments
217
+ ```bash
218
+ openmates server logs --path ~/openmates --tail 200
219
+ openmates server logs --path ~/openmates --container api --follow
220
+ openmates server preflight --path ~/openmates --role core
221
+ openmates server backup --path ~/openmates --role core
222
+ openmates server backup list --path ~/openmates --role core
223
+ openmates server update --path ~/openmates --dry-run
224
+ openmates server update --path ~/openmates
225
+ openmates server update --path ~/openmates --image-tag v0.14.0
226
+ openmates server update --path ~/openmates --channel dev
227
+ openmates server stop --path ~/openmates
228
+ openmates server uninstall --path ~/openmates --yes
229
+ ```
230
+
231
+ Image-mode updates refresh the packaged runtime template, update
232
+ `OPENMATES_IMAGE_TAG`, pull prebuilt images, restart containers, and wait for
233
+ health checks. Before replacing data-bearing roles, the CLI creates a rotating
234
+ latest pre-update backup unless explicitly skipped by the update path.
42
235
 
43
- The CLI derives the web app URL from the API URL so pair-auth lands on the matching backend.
236
+ For source-mode contributor installs:
237
+
238
+ ```bash
239
+ openmates server install --from-source --path ~/openmates-source
240
+ openmates server install --source-path /path/to/OpenMates --path /tmp/openmates-selfhost
241
+ openmates server restart --path ~/openmates-source --rebuild
242
+ ```
243
+
244
+ Source mode uses Git and rebuilds Docker images locally.
245
+
246
+ ## Targets and Environment Variables
247
+
248
+ The CLI derives the web app URL from the API URL so pair-auth opens the matching
249
+ environment.
44
250
 
45
251
  | Target | Command prefix |
46
252
  | --- | --- |
47
- | Production | _(none)_ |
253
+ | OpenMates cloud | none |
48
254
  | Dev server | `OPENMATES_API_URL=https://api.dev.openmates.org` |
49
- | Installed self-hosted server | _(none after `openmates server install`)_ |
255
+ | Installed self-hosted server | none after `openmates server install` |
50
256
  | Remote self-hosted server | `OPENMATES_API_URL=https://api.example.com` |
51
257
 
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`.
258
+ Useful variables:
53
259
 
54
- ## Safety Limits
260
+ | Variable | Purpose |
261
+ | --- | --- |
262
+ | `OPENMATES_API_URL` | Override the API endpoint. |
263
+ | `OPENMATES_APP_URL` | Override the derived web app URL for pair-auth. |
264
+ | `OPENMATES_API_KEY` | API key for app-skill and SDK calls. |
55
265
 
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`.
266
+ You can also pass `--api-url <url>`, `--api-key <key>`, and `--json` to most
267
+ commands.
57
268
 
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.
269
+ ## Local Files
59
270
 
60
- ## SDK
271
+ The CLI stores local state under `~/.openmates/` with owner-only permissions.
61
272
 
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.
273
+ | File | Purpose |
274
+ | --- | --- |
275
+ | `session.json` | Pair-auth CLI session. |
276
+ | `sync_cache.json` | Cached decrypted account data for CLI use. |
277
+ | `server.json` | Self-host install path and local API target. |
278
+ | `remote-sources.json` | Local source bridge metadata. |
279
+
280
+ Treat these files like account credentials.
281
+
282
+ ## Node.js SDK
283
+
284
+ The npm package also exports an API-key SDK for Node.js. Use it when you want a
285
+ programmatic client instead of shell commands.
63
286
 
64
287
  ```ts
65
288
  import { OpenMates } from "openmates";
@@ -69,23 +292,29 @@ const om = new OpenMates({ apiKey: process.env.OPENMATES_API_KEY });
69
292
  const search = await om.apps.web.search({
70
293
  requests: [{ query: "OpenMates SDK examples" }],
71
294
  });
295
+
296
+ const response = await om.chats.send("Summarize this release note draft.");
72
297
  ```
73
298
 
74
- SDK methods authenticate lazily; there is no `connect()` call.
299
+ SDK chats are non-persistent by default. Use `saveToAccount: true` only when you
300
+ intentionally want the chat saved to the OpenMates account.
75
301
 
76
- ```ts
77
- const latestChats = await om.chats.list(); // defaults to 10
78
- const allChats = await om.chats.list({ limit: 0 });
302
+ ## Versioning
79
303
 
80
- await om.chats.send("Summarize this release note draft.");
304
+ OpenMates shows the short product line, for example `v0.14`, in the web app.
305
+ The npm package uses exact artifact versions:
81
306
 
82
- await om.chats.send("Create a project kickoff checklist.", { saveToAccount: true });
307
+ - `0.14.N-alpha.0` is a prerelease from the `dev` branch published under the
308
+ `alpha` npm tag.
309
+ - `0.14.N` is a stable release from `main` published under the `latest` npm tag.
83
310
 
84
- await om.billing.overview();
85
- await om.billing.invoices();
86
- await om.docs.search("api keys");
87
- ```
311
+ Install stable releases with `npm install -g openmates`. Install prereleases with
312
+ `npm install -g openmates@alpha`.
88
313
 
89
- New SDK chats are non-persistent by default. Use `saveToAccount: true` only when you intentionally want the chat saved to the OpenMates account.
314
+ ## More Documentation
90
315
 
91
- Source docs: `docs/user-guide/developers/sdk.md` in the OpenMates repository.
316
+ - [CLI guide](https://openmates.org/docs/user-guide/cli)
317
+ - [Self-hosting setup](https://openmates.org/docs/self-hosting/setup)
318
+ - [SDK guide](https://openmates.org/docs/user-guide/developers/sdk)
319
+ - [Source code](https://github.com/glowingkitty/OpenMates/tree/dev/frontend/packages/openmates-cli)
320
+ - [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.2-alpha.0",
4
4
  "description": "OpenMates CLI and SDK",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",