@sol-merrai/cli 0.1.3 → 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 +122 -81
- package/dist/bin.mjs +834 -0
- package/dist/bin.mjs.map +1 -0
- package/dist/index.d.mts +590 -25
- package/dist/index.d.mts.map +1 -1
- package/dist/index.mjs +135 -2
- package/dist/index.mjs.map +1 -0
- package/package.json +8 -6
- package/.env.example +0 -3
- package/.env.prod.example +0 -3
- package/dist/cli.d.mts +0 -1
- package/dist/cli.mjs +0 -234
- package/dist/cli.mjs.map +0 -1
- package/dist/client-BirYnOM4.mjs +0 -27
- package/dist/client-BirYnOM4.mjs.map +0 -1
package/README.md
CHANGED
|
@@ -1,132 +1,173 @@
|
|
|
1
1
|
# Merrai CLI
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
3
|
+
The Merrai CLI stores, recalls, and imports memories from a terminal. The npm
|
|
4
|
+
package is `@sol-merrai/cli`; the installed command is `merrai`.
|
|
5
5
|
|
|
6
|
-
|
|
7
|
-
`merrai`.
|
|
6
|
+
## Requirements and installation
|
|
8
7
|
|
|
9
|
-
|
|
8
|
+
- Node.js 20 or newer
|
|
10
9
|
|
|
11
10
|
```bash
|
|
12
11
|
npm install -g @sol-merrai/cli
|
|
12
|
+
merrai --help
|
|
13
13
|
```
|
|
14
14
|
|
|
15
|
-
##
|
|
15
|
+
## Authentication
|
|
16
|
+
|
|
17
|
+
Validate and save an API key:
|
|
16
18
|
|
|
17
19
|
```bash
|
|
18
|
-
merrai
|
|
19
|
-
merrai
|
|
20
|
-
merrai
|
|
21
|
-
merrai usage-summary --api-key "merrai_..."
|
|
22
|
-
merrai add-memory --memory "Met Sarah at lunch" --source cli --lobe people
|
|
23
|
-
merrai rpc healthCheck
|
|
20
|
+
merrai auth set-key
|
|
21
|
+
merrai auth status --format text
|
|
22
|
+
merrai auth logout
|
|
24
23
|
```
|
|
25
24
|
|
|
26
|
-
|
|
25
|
+
`auth set-key` prompts without echoing the key when stdin is a TTY. For CI,
|
|
26
|
+
provide `MERRAI_API_KEY`; `--api-key` and a positional key remain available but
|
|
27
|
+
may expose the key in shell history.
|
|
27
28
|
|
|
28
|
-
|
|
29
|
+
Configuration precedence is:
|
|
29
30
|
|
|
30
|
-
|
|
31
|
+
1. Command flags
|
|
32
|
+
2. `MERRAI_*` environment variables
|
|
33
|
+
3. Saved credentials
|
|
34
|
+
4. `https://api.merrai.app`
|
|
31
35
|
|
|
32
|
-
|
|
36
|
+
Credentials are stored at `$XDG_CONFIG_HOME/merrai/credentials.json`, or
|
|
37
|
+
`~/.config/merrai/credentials.json` when `XDG_CONFIG_HOME` is unset. The CLI and
|
|
38
|
+
Claude Code plugin share this versioned file. Existing
|
|
39
|
+
`~/.merrai-claude-code/credentials.json` files remain readable as a migration
|
|
40
|
+
fallback and are not deleted automatically.
|
|
33
41
|
|
|
34
|
-
|
|
42
|
+
`merrai auth logout` is an explicit removal action and deletes both shared and
|
|
43
|
+
legacy fallback credentials after confirmation.
|
|
35
44
|
|
|
36
|
-
|
|
45
|
+
There is intentionally no separate persistent `config.json` yet: the only
|
|
46
|
+
persistent non-secret value is the base URL associated with a credential.
|
|
47
|
+
Flags and environment variables cover temporary overrides without creating an
|
|
48
|
+
empty configuration abstraction.
|
|
37
49
|
|
|
38
|
-
|
|
50
|
+
Supported environment variables:
|
|
39
51
|
|
|
40
|
-
|
|
52
|
+
- `MERRAI_API_KEY`
|
|
53
|
+
- `MERRAI_BASE_URL`
|
|
54
|
+
- `MERRAI_COOKIE`
|
|
55
|
+
- `XDG_CONFIG_HOME`
|
|
41
56
|
|
|
42
|
-
|
|
57
|
+
Installed-package `.env` files are not loaded.
|
|
43
58
|
|
|
44
|
-
|
|
59
|
+
## Command structure
|
|
45
60
|
|
|
46
|
-
|
|
61
|
+
```text
|
|
62
|
+
merrai health
|
|
63
|
+
merrai session
|
|
64
|
+
merrai account usage
|
|
65
|
+
merrai memory add|search|list|profile|by-date|status|clear
|
|
66
|
+
merrai entity find|memories
|
|
67
|
+
merrai document list|get
|
|
68
|
+
merrai ingest memories|chat|chats
|
|
69
|
+
merrai auth set-key|status|logout
|
|
70
|
+
merrai debug rpc
|
|
71
|
+
```
|
|
47
72
|
|
|
48
|
-
|
|
49
|
-
| ------------------- | -------- | -------------------------------------------------------- |
|
|
50
|
-
| `--memory <text>` | Yes | The memory text (also accepted as a positional argument) |
|
|
51
|
-
| `--source <text>` | No | Source identifier (defaults to `"testing-ui"`) |
|
|
52
|
-
| `--lobe <name>` | No | Lobe to store the memory in (defaults to `"main"`) |
|
|
53
|
-
| `--lobe-key <name>` | No | Deprecated alias for `--lobe` |
|
|
73
|
+
Examples:
|
|
54
74
|
|
|
55
|
-
|
|
75
|
+
```bash
|
|
76
|
+
merrai memory add "Met Sarah at lunch"
|
|
77
|
+
merrai memory search "What did Sarah suggest?" --limit 10
|
|
78
|
+
merrai memory by-date --start "2026-07-01T00:00:00Z"
|
|
79
|
+
merrai entity find "Sarah" --type person
|
|
80
|
+
merrai entity memories ent_123
|
|
81
|
+
merrai document list
|
|
82
|
+
merrai document get lvd_123
|
|
83
|
+
merrai memory clear people --yes
|
|
84
|
+
```
|
|
56
85
|
|
|
57
|
-
|
|
86
|
+
`memory clear` confirms interactively and requires `--yes` in noninteractive
|
|
87
|
+
use.
|
|
58
88
|
|
|
59
|
-
|
|
60
|
-
| ---------------- | -------- | ----------------------------------- |
|
|
61
|
-
| `--input <json>` | No | JSON input to pass to the procedure |
|
|
89
|
+
## MCP parity
|
|
62
90
|
|
|
63
|
-
|
|
91
|
+
Every Merrai MCP tool has a canonical CLI command and a compatibility spelling:
|
|
64
92
|
|
|
65
|
-
|
|
|
66
|
-
|
|
|
67
|
-
|
|
|
68
|
-
|
|
|
69
|
-
|
|
|
70
|
-
|
|
|
71
|
-
|
|
|
93
|
+
| MCP tool | Canonical command | Compatibility spelling |
|
|
94
|
+
| --------------------------- | ----------------- | --------------------------- |
|
|
95
|
+
| `add_memory` | `memory add` | `add-memory` |
|
|
96
|
+
| `search_memory` | `memory search` | `search` |
|
|
97
|
+
| `whoAmI` | `memory profile` | `who-am-i`, `whoami` |
|
|
98
|
+
| `list_living_documents` | `document list` | `list-living-documents` |
|
|
99
|
+
| `read_living_document` | `document get` | `read-living-document` |
|
|
100
|
+
| `find_entity` | `entity find` | `find-entity` |
|
|
101
|
+
| `search_memories_by_entity` | `entity memories` | `search-memories-by-entity` |
|
|
102
|
+
| `search_memories_by_date` | `memory by-date` | `search-memories-by-date` |
|
|
72
103
|
|
|
73
|
-
|
|
104
|
+
The canonical commands use the same input limits, defaults, and structured
|
|
105
|
+
response DTOs as their MCP tools. `add-memory` and `search` preserve the older
|
|
106
|
+
CLI-only options and response shapes; the other compatibility spellings are
|
|
107
|
+
aliases for the canonical contract. They do not emit deprecation warnings.
|
|
74
108
|
|
|
75
|
-
|
|
109
|
+
## Files and stdin
|
|
110
|
+
|
|
111
|
+
Bulk commands accept inline JSON, a file, or stdin:
|
|
76
112
|
|
|
77
113
|
```bash
|
|
78
|
-
merrai memories --
|
|
114
|
+
merrai ingest memories --input '[{"memory":"Remember this"}]'
|
|
115
|
+
merrai ingest memories --file ./memories.json
|
|
116
|
+
cat memories.json | merrai ingest memories --file -
|
|
117
|
+
cat chats.json | merrai ingest chats --file -
|
|
118
|
+
printf 'A multiline memory\nwith context\n' | merrai memory add --file -
|
|
79
119
|
```
|
|
80
120
|
|
|
81
|
-
|
|
121
|
+
Supplying more than one input source is a usage error.
|
|
82
122
|
|
|
83
|
-
|
|
84
|
-
export MERRAI_BASE_URL="https://api.example.com"
|
|
85
|
-
export MERRAI_API_KEY="merrai_..."
|
|
123
|
+
## Output contract
|
|
86
124
|
|
|
87
|
-
|
|
88
|
-
|
|
125
|
+
JSON is always the default machine contract, including scalar string results.
|
|
126
|
+
Use `--format text` for concise human output. `--json` is an alias for
|
|
127
|
+
`--format json`.
|
|
89
128
|
|
|
90
|
-
|
|
129
|
+
- Result data is written to stdout.
|
|
130
|
+
- Diagnostics and errors are written to stderr.
|
|
131
|
+
- JSON output is never mixed with progress or error text.
|
|
132
|
+
- Successful canonical MCP-parity commands emit the MCP tool's structured DTO
|
|
133
|
+
directly, without an additional envelope.
|
|
134
|
+
- `NO_COLOR` is naturally honored because the CLI emits no color in machine
|
|
135
|
+
output.
|
|
91
136
|
|
|
92
|
-
|
|
93
|
-
- `MERRAI_API_KEY`: Personal API key. Sent as the `x-api-key` header.
|
|
94
|
-
- `MERRAI_COOKIE`: Optional session cookie fallback.
|
|
137
|
+
Exit codes:
|
|
95
138
|
|
|
96
|
-
|
|
97
|
-
|
|
139
|
+
| Code | Meaning |
|
|
140
|
+
| ---- | --------------------------------------- |
|
|
141
|
+
| `0` | Success |
|
|
142
|
+
| `2` | Usage or validation error |
|
|
143
|
+
| `3` | Authentication or authorization failure |
|
|
144
|
+
| `4` | Not found or conflict |
|
|
145
|
+
| `5` | Rate limit or resource exhaustion |
|
|
146
|
+
| `10` | Network or server failure |
|
|
98
147
|
|
|
99
|
-
|
|
100
|
-
- `.env.prod` when `MERRAI_ENV=prod` or `NODE_ENV=production`
|
|
101
|
-
- `.env.local` as the final override
|
|
148
|
+
## Raw oRPC access
|
|
102
149
|
|
|
103
|
-
|
|
150
|
+
`debug rpc` is an unstable escape hatch for top-level procedures:
|
|
104
151
|
|
|
105
152
|
```bash
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
153
|
+
merrai debug rpc healthCheck
|
|
154
|
+
merrai debug rpc memoryStatus --input '{"lobeKey":"main"}'
|
|
155
|
+
merrai debug rpc addMemories --file ./payload.json
|
|
109
156
|
```
|
|
110
157
|
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
```bash
|
|
114
|
-
MERRAI_BASE_URL=https://api.merrai.app
|
|
115
|
-
MERRAI_API_KEY=
|
|
116
|
-
MERRAI_COOKIE=
|
|
117
|
-
```
|
|
158
|
+
## Reusable client
|
|
118
159
|
|
|
119
|
-
|
|
160
|
+
The package exposes both client contracts from `@sol-merrai/cli`:
|
|
120
161
|
|
|
121
|
-
```
|
|
122
|
-
|
|
162
|
+
```ts
|
|
163
|
+
import {
|
|
164
|
+
createMerraiClient,
|
|
165
|
+
createMerraiThrowingClient,
|
|
166
|
+
} from "@sol-merrai/cli";
|
|
123
167
|
```
|
|
124
168
|
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
- API key auth via `--api-key` or `MERRAI_API_KEY`.
|
|
130
|
-
- Session cookie auth via `--cookie` or `MERRAI_COOKIE`.
|
|
169
|
+
- `createMerraiThrowingClient()` returns typed data and throws oRPC/network
|
|
170
|
+
errors. New integrations should use it.
|
|
171
|
+
- `createMerraiClient()` retains the legacy `[error, data]` safe-tuple contract.
|
|
131
172
|
|
|
132
|
-
|
|
173
|
+
There is no separate SDK package or method-by-method SDK facade.
|