@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 CHANGED
@@ -1,132 +1,173 @@
1
1
  # Merrai CLI
2
2
 
3
- Command-line client for sending memories to Merrai and calling the Merrai API
4
- with a personal API key.
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
- The npm package is published as `@sol-merrai/cli`; the installed command is
7
- `merrai`.
6
+ ## Requirements and installation
8
7
 
9
- ## Installation
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
- ## Usage
15
+ ## Authentication
16
+
17
+ Validate and save an API key:
16
18
 
17
19
  ```bash
18
- merrai health
19
- merrai session --api-key "merrai_..."
20
- merrai memories --api-key "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
- ## Commands
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
- ### `health`
29
+ Configuration precedence is:
29
30
 
30
- Check API connectivity.
31
+ 1. Command flags
32
+ 2. `MERRAI_*` environment variables
33
+ 3. Saved credentials
34
+ 4. `https://api.merrai.app`
31
35
 
32
- ### `session`
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
- Fetch the current session.
42
+ `merrai auth logout` is an explicit removal action and deletes both shared and
43
+ legacy fallback credentials after confirmation.
35
44
 
36
- ### `memories`
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
- List memories for the current user.
50
+ Supported environment variables:
39
51
 
40
- ### `usage-summary`
52
+ - `MERRAI_API_KEY`
53
+ - `MERRAI_BASE_URL`
54
+ - `MERRAI_COOKIE`
55
+ - `XDG_CONFIG_HOME`
41
56
 
42
- Fetch current usage summary.
57
+ Installed-package `.env` files are not loaded.
43
58
 
44
- ### `add-memory`
59
+ ## Command structure
45
60
 
46
- Queue a memory for processing.
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
- | Flag | Required | Description |
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
- ### `rpc <procedure>`
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
- Call a top-level oRPC procedure directly.
86
+ `memory clear` confirms interactively and requires `--yes` in noninteractive
87
+ use.
58
88
 
59
- | Flag | Required | Description |
60
- | ---------------- | -------- | ----------------------------------- |
61
- | `--input <json>` | No | JSON input to pass to the procedure |
89
+ ## MCP parity
62
90
 
63
- ## Global Options
91
+ Every Merrai MCP tool has a canonical CLI command and a compatibility spelling:
64
92
 
65
- | Flag | Description |
66
- | ------------------- | ------------------------------------------ |
67
- | `--base-url <url>` | API base URL (overrides `MERRAI_BASE_URL`) |
68
- | `--api-key <key>` | API key for protected procedures |
69
- | `--cookie <cookie>` | Session cookie for protected procedures |
70
- | `--json` | Always print JSON output |
71
- | `-h`, `--help` | Show help text |
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
- ## Configuration
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
- You can pass settings as flags:
109
+ ## Files and stdin
110
+
111
+ Bulk commands accept inline JSON, a file, or stdin:
76
112
 
77
113
  ```bash
78
- merrai memories --base-url "https://api.example.com" --api-key "merrai_..."
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
- Or use environment variables:
121
+ Supplying more than one input source is a usage error.
82
122
 
83
- ```bash
84
- export MERRAI_BASE_URL="https://api.example.com"
85
- export MERRAI_API_KEY="merrai_..."
123
+ ## Output contract
86
124
 
87
- merrai memories
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
- Supported variables:
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
- - `MERRAI_BASE_URL`: Merrai API base URL.
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
- When running from a checked-out repository, the CLI also loads package-local env
97
- files in this order:
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
- - `.env`
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
- Example `.env`:
150
+ `debug rpc` is an unstable escape hatch for top-level procedures:
104
151
 
105
152
  ```bash
106
- MERRAI_BASE_URL=http://localhost:3000
107
- MERRAI_API_KEY=
108
- MERRAI_COOKIE=
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
- Example `.env.prod`:
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
- Use it with:
160
+ The package exposes both client contracts from `@sol-merrai/cli`:
120
161
 
121
- ```bash
122
- MERRAI_ENV=prod merrai memories
162
+ ```ts
163
+ import {
164
+ createMerraiClient,
165
+ createMerraiThrowingClient,
166
+ } from "@sol-merrai/cli";
123
167
  ```
124
168
 
125
- ## Authentication
126
-
127
- Protected commands support either:
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
- API keys are the recommended option for CLI usage.
173
+ There is no separate SDK package or method-by-method SDK facade.