@martenhq/cli 0.0.0-stage → 0.1.0

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,93 @@
-# 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). `marten logout` revokes it; signing in again replaces it.
+
+A key has scopes. By default: `martens` (your Martens and their 1:1s with you), `tasks` and `registry`. For your
+groups, ask for more:
+
+```sh
+marten login --scope martens --scope tasks --scope registry --scope chats:read --scope chats:write
+```
+
+In CI or for another agent, set `MARTEN_API_KEY` instead (and `MARTEN_API_URL` for a server other than
+https://api.marten.sh).
+
+## 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