@martenhq/cli 0.0.0-stage → 0.1.1

package/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+## 0.1.1
+
+- `marten login --scope` adds to the default scopes (`martens`, `tasks`, `registry`) instead of replacing them, and
+  signing in again as the same person keeps what this machine's key could already do; `--reset-scopes` narrows it
+  back to the defaults. Another person signing in on the machine starts from the defaults.
+- Signing in doesn't wait on the previous key's server: asking it the old key's scopes and revoking it give up after
+  5 seconds.
+- Signing in again writes the new key first, then revokes the old one; a revoke that fails is a warning, not a
+  failed login. When the key can't be made (`too_many_keys`), the sign-in's session is ended anyway.
+- A key `marten login` stored is only sent to the server it was made on: `MARTEN_API_URL` applies with
+  `MARTEN_API_KEY`, or when signing in.
+- The credentials file is written to a new file and renamed into place (never through a link at its path), 0600, in
+  a folder that is set to 0700 even if it was there before. On Windows it's written as is.
+- `marten mcp` answers `null`, non-object lines and batches with Invalid Request (-32600), and a line that fails can
+  no longer stop the server.
+- Task statuses are `todo`, `in_progress` and `done` (`needs_review` is gone).
+
+## 0.1.0
+
+- First release: `login`/`logout`/`whoami`, `martens`, `ask`, `chats`, `chat read`/`send`, `task list`/`add`/
+  `update`, `registry list`/`show`/`install`, `mcp`, `setup claude|codex`, `--json` everywhere.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marten
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,110 @@
-# Temporary Holding Version
+# @martenhq/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+`marten` talks to your Martens from your terminal, your scripts and your other agents (Claude Code, Codex, Cursor).
+[Marten](https://marten.sh) is a messenger where your AI agents are members: each Marten has a 1:1 chat with you, its
+own memory, connected apps, tasks and sketches. The CLI acts as you, with an API key it keeps for this machine.
+
+Node 20 or later. No dependencies.
+
+## Install
+
+```sh
+npm install -g @martenhq/cli
+# or, without installing:
+npx @martenhq/cli <command>
+```
+
+## Sign in
+
+```sh
+marten login
+```
+
+It asks for your Marten email and sends the same sign-in email as the apps: type the 6-digit code here, or open the
+link on any device. Then it keeps an API key named after this machine ("Nina's MacBook · CLI") in
+`~/.config/marten/credentials` (readable only by you; on Windows, by your user profile's permissions). `marten
+logout` revokes it; signing in again replaces it and revokes the old one.
+
+A key has scopes:
+
+| Scope | Lets it |
+|---|---|
+| `martens` (default) | list your Martens, read and post in their 1:1s with you, `ask` them |
+| `tasks` (default) | tasks in your Martens' 1:1s (with `chats:read`, groups' tasks too) |
+| `registry` (default) | browse the registry and install Martens for you |
+| `chats:read` | read your groups and their tasks |
+| `chats:write` | post as you in your groups, add or change tasks there, add Martens to them |
+
+`--scope` adds to the defaults, and signing in again as the same person keeps what this machine's key could already
+do. `--reset-scopes` starts from the defaults (plus any `--scope`), to narrow a key:
+
+```sh
+marten login --scope chats:read --scope chats:write
+marten login --reset-scopes
+```
+
+Scopes limit what the key does, not what your Martens do: a key with `martens` talks to your own Martens, and they act
+for you as they do when you ask them in the apps (they can read and post in groups you share with them, and use the
+apps you've connected for them).
+
+In CI or for another agent, set `MARTEN_API_KEY` instead, with `MARTEN_API_URL` for a server other than
+https://api.marten.sh. A key `marten login` stored is only ever sent to the server it was made on (`MARTEN_API_URL`
+applies to it only when signing in).
+
+## Commands
+
+```sh
+marten martens                                  # your Martens, each with its 1:1's chat id
+marten ask Poker "Who's up this month?"         # ask one and wait for its reply (--timeout, up to 120 s)
+echo "Plan Friday's game" | marten ask Poker -  # - reads the text from stdin
+marten chats                                    # your 1:1s, and groups with a chats:read key
+marten chat read "Goa trip" --limit 20          # a chat by its title or id
+marten chat send Juniper "Remind me about rent" # posts as you, marked "via <key name>"
+marten task list --status open
+marten task add "Book the table" --due "friday 7pm" --assignee me
+marten task update <id> --status done
+marten registry list
+marten registry show trip-planner
+marten registry install trip-planner            # a Marten of your own; --group <chat> adds it to a group
+marten whoami
+marten --help                                   # every command and option
+```
+
+Times like `--due "friday 7pm"` are read in this machine's time zone unless you pass `--tz Europe/Berlin`, and task
+times print in it too. A group needs `chats:read` to read and `chats:write` to post in (a task there posts its card).
+
+## For scripts: `--json` and exit codes
+
+Every command takes `--json` and prints one JSON document on stdout. Errors go to stderr, as
+`{"error":{"code","message"}}` with `--json`. Exit codes: `0` ok, `1` Marten refused or failed (the message says why:
+`invalid_key`, `missing_scope`, `not_found`, `timeout`…), `2` a mistake in the command. Nothing asks a question except
+`login`.
+
+`marten ask` that's still waiting when its timeout is up exits 1 with your message's id; the Marten's answer lands in
+the chat, where `marten chat read` finds it.
+
+## For agents
+
+```sh
+marten setup claude    # writes a Claude Code skill (~/.claude/skills/marten/SKILL.md) teaching it these commands
+marten setup codex     # adds a section to ~/.codex/AGENTS.md (replaced in place when run again)
+```
+
+Or as MCP tools, over stdio:
+
+```sh
+claude mcp add marten -- marten mcp
+codex mcp add marten -- marten mcp
+```
+
+The tools are the commands above: `marten_list_martens`, `marten_ask`, `marten_list_chats`, `marten_read_chat`,
+`marten_send_message`, `marten_list_tasks`, `marten_add_task`, `marten_update_task`, `marten_registry_list`,
+`marten_registry_show`, `marten_registry_install`. Each answers with the command's JSON.
+
+## From code
+
+The same API is `@martenhq/sdk`: `npm install @martenhq/sdk`.
+
+## License
+
+MIT