reef-cli 0.1.0__tar.gz → 2.0.0__tar.gz

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.
reef_cli-2.0.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Haai BV
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -1,15 +1,16 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: reef-cli
3
- Version: 0.1.0
3
+ Version: 2.0.0
4
4
  Summary: Command-line client for reef — shared, living memory for people and their AI assistants
5
5
  Keywords: mcp,memory,cli,reef
6
6
  Author: WOUTER DURNEZ
7
7
  Author-email: WOUTER DURNEZ <wouter.durnez@gmail.com>
8
8
  License-Expression: MIT
9
+ License-File: LICENSE
9
10
  Requires-Dist: fastmcp>=2
10
11
  Requires-Python: >=3.13
11
12
  Project-URL: Homepage, https://reefwith.me
12
- Project-URL: Repository, https://github.com/diepzee/rif
13
+ Project-URL: Repository, https://github.com/diepzee/reef
13
14
  Description-Content-Type: text/markdown
14
15
 
15
16
  # reef-cli
@@ -0,0 +1,30 @@
1
+ [project]
2
+ name = "reef-cli"
3
+ version = "2.0.0"
4
+ description = "Command-line client for reef — shared, living memory for people and their AI assistants"
5
+ readme = "README.md"
6
+ license = "MIT"
7
+ license-files = ["LICENSE"]
8
+ requires-python = ">=3.13"
9
+ dependencies = ["fastmcp>=2"]
10
+ keywords = [
11
+ "mcp",
12
+ "memory",
13
+ "cli",
14
+ "reef",
15
+ ]
16
+
17
+ [[project.authors]]
18
+ name = "WOUTER DURNEZ"
19
+ email = "wouter.durnez@gmail.com"
20
+
21
+ [project.urls]
22
+ Homepage = "https://reefwith.me"
23
+ Repository = "https://github.com/diepzee/reef"
24
+
25
+ [project.scripts]
26
+ reef = "reef_cli.cli:main"
27
+
28
+ [build-system]
29
+ requires = ["uv_build>=0.11.14,<0.12.0"]
30
+ build-backend = "uv_build"
@@ -1,12 +1,13 @@
1
1
  [project]
2
2
  name = "reef-cli"
3
- version = "0.1.0"
3
+ version = "2.0.0"
4
4
  description = "Command-line client for reef — shared, living memory for people and their AI assistants"
5
5
  readme = "README.md"
6
6
  authors = [
7
7
  { name = "WOUTER DURNEZ", email = "wouter.durnez@gmail.com" }
8
8
  ]
9
9
  license = "MIT"
10
+ license-files = ["LICENSE"]
10
11
  requires-python = ">=3.13"
11
12
  dependencies = [
12
13
  "fastmcp>=2",
@@ -15,7 +16,7 @@ keywords = ["mcp", "memory", "cli", "reef"]
15
16
 
16
17
  [project.urls]
17
18
  Homepage = "https://reefwith.me"
18
- Repository = "https://github.com/diepzee/rif"
19
+ Repository = "https://github.com/diepzee/reef"
19
20
 
20
21
  [project.scripts]
21
22
  reef = "reef_cli.cli:main"
@@ -251,217 +251,228 @@ def build_parser() -> argparse.ArgumentParser:
251
251
  help="JSON object, @file, or '-' for stdin (default: {})",
252
252
  )
253
253
 
254
- _tool_parser(sub, "load_index", "load the body-free memory index")
255
- read_pages = _tool_parser(sub, "read_pages", "read several pages from one space")
256
- read_pages.add_argument("space")
257
- read_pages.add_argument("paths", nargs="+")
258
- _tool_parser(sub, "load_all_context", "load all page bodies for maintenance")
259
- _tool_parser(sub, "get_operating_protocol", "load the protocol and persona")
260
- read_page = _tool_parser(sub, "read_page", "read one page")
261
- read_page.add_argument("space")
262
- read_page.add_argument("path")
263
- _tool_parser(sub, "list_spaces", "list spaces, members, ownership, and versions")
264
- create_space = _tool_parser(sub, "create_space", "create a shared space")
265
- create_space.add_argument("slug")
266
- invite = _tool_parser(sub, "invite", "invite a person into a shared space")
267
- invite.add_argument("space")
268
- invite.add_argument("email")
269
- invite.add_argument("--display-name")
270
- invite_reef = _tool_parser(
271
- sub, "invite_to_reef", "invite someone to Reef without sharing a space"
272
- )
273
- invite_reef.add_argument("email")
274
- invite_reef.add_argument("--display-name")
275
- remove = _tool_parser(sub, "remove_member", "remove a shared-space member")
276
- remove.add_argument("space")
277
- remove.add_argument("email")
278
- leave = _tool_parser(sub, "leave_space", "leave a shared space, handing it on")
279
- leave.add_argument("space")
280
- delete = _tool_parser(
281
- sub, "delete_space", "destroy a shared space you are alone in"
254
+ _build_tool_parsers(sub)
255
+ return parser
256
+
257
+
258
+ def _reasoned(parser: argparse.ArgumentParser) -> argparse.ArgumentParser:
259
+ """Give a tool's parser the optional ``--reason`` every tool but two takes.
260
+
261
+ :param parser: the tool's parser
262
+ :returns: the same parser
263
+ """
264
+ parser.add_argument(
265
+ "--reason",
266
+ default="",
267
+ help="why you make this call, in a few words; Reef logs it privately "
268
+ "for the person, to improve Reef",
282
269
  )
283
- delete.add_argument("space")
284
- remember = _tool_parser(sub, "remember", "append a fact to a space inbox")
285
- remember.add_argument("fact", help="fact text; '-' reads stdin")
286
- remember.add_argument("--space", default="personal")
270
+ return parser
287
271
 
288
- write = _tool_parser(sub, "write_page", "create or replace one Markdown page")
289
- write.add_argument("space")
290
- write.add_argument("path")
291
- _add_text_source(write, "body")
292
- write.add_argument("--message", required=True)
293
- write.add_argument("--title")
294
- write.add_argument("--tag", dest="tags", action="append")
295
- write.add_argument("--expected-version", type=int)
296
-
297
- writes = _tool_parser(sub, "write_pages", "atomically write up to 20 pages")
298
- writes.add_argument("space")
299
- writes.add_argument("pages", help="JSON array, @file, or '-' for stdin")
300
- writes.add_argument("--message", default="")
301
-
302
- edit = _tool_parser(sub, "edit_page_section", "replace one exact page span")
303
- edit.add_argument("space")
304
- edit.add_argument("path")
305
- _add_text_source(edit, "old-text")
306
- _add_text_source(edit, "new-text")
307
- edit.add_argument("--message", required=True)
308
- edit.add_argument("--expected-version", type=int)
309
-
310
- meta = _tool_parser(sub, "update_meta_page", "replace the personal persona page")
311
- _add_text_source(meta, "body")
312
- meta.add_argument("--message", required=True)
313
- meta.add_argument(
272
+
273
+ def _confirmable(parser: argparse.ArgumentParser) -> None:
274
+ """Give a staged tool's parser the ``--confirm`` of its second call.
275
+
276
+ :param parser: the parser of ``share``, ``forget`` or ``instruct``
277
+ """
278
+ parser.add_argument(
314
279
  "--confirm",
315
- action="store_true",
316
- help="confirm that the user agreed to this persona change",
280
+ metavar="TOKEN",
281
+ help="the token the first call returned, once the person said yes; "
282
+ "leave out for the first call",
317
283
  )
318
284
 
319
- prepare = _tool_parser(
320
- sub, "prepare_to_share", "stage personal content for sharing"
321
- )
322
- prepare.add_argument("path")
323
- prepare.add_argument("dest_space")
324
- prepare.add_argument("--section")
325
- prepare.add_argument("--section-file")
326
- prepare.add_argument("--dest-path")
327
- confirm = _tool_parser(sub, "confirm_share", "execute a staged share")
328
- confirm.add_argument("nonce")
329
-
330
- add_file = _tool_parser(
331
- sub, "add_file", "upload a file with a searchable description"
332
- )
333
- add_file.add_argument("space")
334
- add_file.add_argument("file", type=Path)
335
- add_file.add_argument("--mime")
336
- add_file.add_argument("--description", required=True)
337
- add_file.add_argument("--page-path")
338
- read_file = _tool_parser(sub, "read_file", "get file metadata and a signed URL")
339
- read_file.add_argument("space")
340
- read_file.add_argument("key")
341
- delete_file = _tool_parser(sub, "delete_file", "permanently delete a stored file")
342
- delete_file.add_argument("space")
343
- delete_file.add_argument("key")
344
-
345
- add_image = _tool_parser(
346
- sub, "add_image", "compatibility alias for uploading an image"
347
- )
348
- add_image.add_argument("space")
349
- add_image.add_argument("file", type=Path)
350
- add_image.add_argument("--mime")
351
- add_image.add_argument("--description", required=True)
352
- add_image.add_argument("--page-path")
353
- read_image = _tool_parser(sub, "read_image", "compatibility alias for read-file")
354
- read_image.add_argument("space")
355
- read_image.add_argument("key")
356
- delete_image = _tool_parser(
357
- sub, "delete_image", "compatibility alias for delete-file"
358
- )
359
- delete_image.add_argument("space")
360
- delete_image.add_argument("key")
361
- return parser
362
285
 
286
+ def _build_tool_parsers(sub: argparse._SubParsersAction) -> None:
287
+ """Add one subcommand for each of the sixteen tools.
363
288
 
364
- def _file_arguments(args: argparse.Namespace, *, image: bool = False) -> dict[str, Any]:
289
+ :param sub: the subparsers of the main parser
290
+ """
291
+
292
+ def tool(name: str, help: str, *, reason: bool = True) -> argparse.ArgumentParser:
293
+ parser = _tool_parser(sub, name, help)
294
+ return _reasoned(parser) if reason else parser
295
+
296
+ tool("load_index", "start here: protocol, persona and the index of every space")
297
+ recall = tool("recall", "answer a question from memory")
298
+ recall.add_argument("question")
299
+ recall.add_argument("--space", help="search one space only")
300
+ recall.add_argument("--limit", type=int, default=5)
301
+ brief = tool("brief", "get ready to advise or prepare on a topic")
302
+ brief.add_argument("topic")
303
+ brief.add_argument("--space", help="look in one space only")
304
+ brief.add_argument("--entries", type=int, default=10)
305
+ open_ = tool("open", "read whole engrams and stored files by ref")
306
+ open_.add_argument("refs", nargs="+", help="<space>/<path> or <space>/file/<key>")
307
+ open_.add_argument("--as-of", help="ISO-8601 moment to read engrams as of")
308
+ catch_up = tool("catch_up", "list what changed in your spaces")
309
+ catch_up.add_argument("--since", help="ISO-8601 moment; default: last 7 days")
310
+ remember = tool("remember", "keep one quick fact in a space's inbox")
311
+ remember.add_argument("fact", help="fact text; '-' reads stdin")
312
+ remember.add_argument("--space", default="personal")
313
+ log = tool("log", "add one entry at the end of a log")
314
+ log.add_argument("space")
315
+ log.add_argument("engram", help="the log's path")
316
+ log.add_argument("--heading", required=True)
317
+ _add_text_source(log, "entry")
318
+ write = tool("write", "create or replace up to 20 whole engrams, atomically")
319
+ write.add_argument("space")
320
+ write.add_argument("engrams", help="JSON array, @file, or '-' for stdin")
321
+ write.add_argument("--message", required=True)
322
+ store = tool("store_file", "keep a document or an image with a description")
323
+ store.add_argument("space")
324
+ store.add_argument("file", type=Path)
325
+ store.add_argument("--mime")
326
+ store.add_argument("--description", required=True)
327
+ store.add_argument("--engram", help="path of the engram the file belongs to")
328
+ correct = tool("correct", "replace one exact passage of an engram")
329
+ correct.add_argument("space")
330
+ correct.add_argument("engram")
331
+ _add_text_source(correct, "old-text")
332
+ _add_text_source(correct, "new-text")
333
+ correct.add_argument("--message", required=True)
334
+ correct.add_argument("--expected-version", type=int)
335
+ undo = tool("undo", "restore an earlier version of an engram")
336
+ undo.add_argument("space")
337
+ undo.add_argument("engram")
338
+ undo.add_argument("--version", type=int)
339
+ forget = tool("forget", "delete an engram or a file for good, in two calls")
340
+ forget.add_argument("space")
341
+ target = forget.add_mutually_exclusive_group(required=True)
342
+ target.add_argument("--engram", help="path of the engram to forget")
343
+ target.add_argument("--file", help="key of the file to forget")
344
+ _confirmable(forget)
345
+ share = tool("share", "move a personal engram into a shared space, in two calls")
346
+ share.add_argument("engram")
347
+ share.add_argument("to_space")
348
+ share.add_argument("--section", help="exact text to share; '-' reads stdin")
349
+ share.add_argument("--section-file", metavar="PATH")
350
+ share.add_argument(
351
+ "--to-path", help="path of the shared engram; needed with a section"
352
+ )
353
+ _confirmable(share)
354
+ instruct = tool("instruct", "replace the persona, in two calls")
355
+ _add_text_source(instruct, "body")
356
+ _confirmable(instruct)
357
+ # The two-tool connector shape, carried here for parity with the MCP
358
+ # surface. They take no reason: some clients can only ever call these two.
359
+ search = tool("search", "search, in the connector shape", reason=False)
360
+ search.add_argument("query")
361
+ fetch = tool("fetch", "fetch one result from search", reason=False)
362
+ fetch.add_argument("id")
363
+
364
+
365
+ def _file_arguments(args: argparse.Namespace) -> dict[str, Any]:
366
+ """Read a file for ``store_file``: its bytes, name and content type.
367
+
368
+ :param args: the parsed ``store-file`` command
369
+ :returns: the arguments of the tool
370
+ :raises CLIError: when the file cannot be read
371
+ """
365
372
  try:
366
373
  data = args.file.read_bytes()
367
374
  except OSError as exc:
368
375
  raise CLIError(f"could not read file {args.file}: {exc}") from exc
369
376
  mime = args.mime or mimetypes.guess_type(args.file.name)[0]
370
- if mime is None:
371
- mime = "application/octet-stream"
372
- result = {
377
+ return {
373
378
  "space": args.space,
379
+ "filename": args.file.name,
374
380
  "data_base64": base64.b64encode(data).decode("ascii"),
375
- "mime": mime,
381
+ "mime": mime or "application/octet-stream",
376
382
  "description": args.description,
377
- "page_path": args.page_path,
383
+ "engram": args.engram,
378
384
  }
379
- if not image:
380
- result["filename"] = args.file.name
381
- return result
382
385
 
383
386
 
384
- def tool_call(args: argparse.Namespace) -> tuple[str, dict[str, Any]]:
385
- """Translate one parsed named command into its exact MCP call."""
387
+ def _arguments(args: argparse.Namespace) -> dict[str, Any]:
388
+ """Turn a parsed tool command into the tool's arguments, without ``reason``.
389
+
390
+ :param args: the parsed command
391
+ :returns: the arguments; optional ones that were not given are left out
392
+ :raises CLIError: when an argument cannot be used
393
+ """
386
394
  tool = args.tool
387
- if tool in {
388
- "load_index",
389
- "load_all_context",
390
- "get_operating_protocol",
391
- "list_spaces",
392
- }:
393
- return tool, {}
394
- if tool == "read_pages":
395
- return tool, {"space": args.space, "paths": args.paths}
396
- if tool == "read_page":
397
- return tool, {"space": args.space, "path": args.path}
398
- if tool == "create_space":
399
- return tool, {"slug": args.slug}
400
- if tool in {"invite", "invite_to_reef"}:
401
- payload = {"email": args.email, "display_name": args.display_name}
402
- if tool == "invite":
403
- payload["space"] = args.space
404
- return tool, payload
405
- if tool == "remove_member":
406
- return tool, {"space": args.space, "email": args.email}
407
- if tool in {"leave_space", "delete_space"}:
408
- return tool, {"space": args.space}
395
+ if tool == "recall":
396
+ return {"question": args.question, "space": args.space, "limit": args.limit}
397
+ if tool == "brief":
398
+ return {"topic": args.topic, "space": args.space, "entries": args.entries}
399
+ if tool == "open":
400
+ return {"refs": args.refs, "as_of": args.as_of}
401
+ if tool == "catch_up":
402
+ return {"since": args.since}
409
403
  if tool == "remember":
410
404
  fact = sys.stdin.read() if args.fact == "-" else args.fact
411
- return tool, {"fact": fact, "space": args.space}
412
- if tool == "write_page":
413
- return tool, {
405
+ return {"fact": fact, "space": args.space}
406
+ if tool == "log":
407
+ return {
414
408
  "space": args.space,
415
- "path": args.path,
416
- "body": _text_source(args.body, args.body_file, "body"),
417
- "message": args.message,
418
- "title": args.title,
419
- "tags": args.tags,
420
- "expected_version": args.expected_version,
409
+ "engram": args.engram,
410
+ "heading": args.heading,
411
+ "entry": _text_source(args.entry, args.entry_file, "entry"),
421
412
  }
422
- if tool == "write_pages":
423
- pages = _json_source(args.pages)
424
- if not isinstance(pages, list):
425
- raise CLIError("write-pages input must be a JSON array")
426
- return tool, {"space": args.space, "pages": pages, "message": args.message}
427
- if tool == "edit_page_section":
428
- return tool, {
413
+ if tool == "write":
414
+ engrams = _json_source(args.engrams)
415
+ if not isinstance(engrams, list):
416
+ raise CLIError("write input must be a JSON array")
417
+ return {"space": args.space, "engrams": engrams, "message": args.message}
418
+ if tool == "store_file":
419
+ return _file_arguments(args)
420
+ if tool == "correct":
421
+ return {
429
422
  "space": args.space,
430
- "path": args.path,
423
+ "engram": args.engram,
431
424
  "old_text": _text_source(args.old_text, args.old_text_file, "old-text"),
432
425
  "new_text": _text_source(args.new_text, args.new_text_file, "new-text"),
433
426
  "message": args.message,
434
427
  "expected_version": args.expected_version,
435
428
  }
436
- if tool == "update_meta_page":
437
- return tool, {
438
- "space": "personal",
439
- "path": "meta/persona.md",
440
- "body": _text_source(args.body, args.body_file, "body"),
441
- "message": args.message,
429
+ if tool == "undo":
430
+ return {"space": args.space, "engram": args.engram, "version": args.version}
431
+ if tool == "forget":
432
+ return {
433
+ "space": args.space,
434
+ "engram": args.engram,
435
+ "file": args.file,
442
436
  "confirm": args.confirm,
443
437
  }
444
- if tool == "prepare_to_share":
438
+ if tool == "share":
445
439
  if args.section is not None and args.section_file is not None:
446
440
  raise CLIError("use only one of --section and --section-file")
447
441
  section = None
448
442
  if args.section is not None or args.section_file is not None:
449
443
  section = _text_source(args.section, args.section_file, "section")
450
- return tool, {
451
- "path": args.path,
452
- "dest_space": args.dest_space,
444
+ return {
445
+ "engram": args.engram,
446
+ "to_space": args.to_space,
453
447
  "section": section,
454
- "dest_path": args.dest_path,
448
+ "to_path": args.to_path,
449
+ "confirm": args.confirm,
450
+ }
451
+ if tool == "instruct":
452
+ return {
453
+ "body": _text_source(args.body, args.body_file, "body"),
454
+ "confirm": args.confirm,
455
455
  }
456
- if tool == "confirm_share":
457
- return tool, {"nonce": args.nonce}
458
- if tool == "add_file":
459
- return tool, _file_arguments(args)
460
- if tool == "add_image":
461
- return tool, _file_arguments(args, image=True)
462
- if tool in {"read_file", "delete_file", "read_image", "delete_image"}:
463
- return tool, {"space": args.space, "key": args.key}
464
- raise CLIError(f"unsupported command: {tool}")
456
+ if tool == "search":
457
+ return {"query": args.query}
458
+ if tool == "fetch":
459
+ return {"id": args.id}
460
+ return {}
461
+
462
+
463
+ def tool_call(args: argparse.Namespace) -> tuple[str, dict[str, Any]]:
464
+ """Translate one parsed named command into its exact MCP call.
465
+
466
+ :param args: the parsed command
467
+ :returns: the tool's name and its arguments: ``reason`` first, when the
468
+ tool takes one, then every argument that was given
469
+ :raises CLIError: when an argument cannot be used
470
+ """
471
+ tool = args.tool
472
+ arguments = {k: v for k, v in _arguments(args).items() if v is not None}
473
+ if tool not in {"search", "fetch"}:
474
+ arguments = {"reason": args.reason, **arguments}
475
+ return tool, arguments
465
476
 
466
477
 
467
478
  def _jsonable(value: Any) -> Any:
File without changes