@grapecool/cli 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Shiny Grape, LLC
+
+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,161 @@
-# Temporary Holding Version
+# Grape 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.
+The official command line tool for [Grape](https://grape.cool), the AI note
+app for Mac, Windows, Linux, iPhone and Android. Read, search and write the
+notes and folders in your Grape account from a terminal, a script or an AI
+agent, and search the Grape help center without signing in.
+
+```sh
+npm install -g @grapecool/cli
+grape login
+grape notes list
+```
+
+Or run it once without installing: `npx @grapecool/cli notes list`.
+Node.js 20 or later.
+
+**What you need**
+
+- **Notes and folders** need a Grape account on the **Pro** plan, the same
+  plan as the ChatGPT and Claude connection. Plus and Lifetime do not
+  include it. [See the plans](https://grape.cool/pricing).
+- **Plans, changelog, downloads and guides** need no account at all.
+
+## Signing in
+
+```sh
+grape login
+```
+
+This opens grape.cool in your browser. Sign in with the Google account you
+use in the Grape apps and choose Allow. The terminal finishes by itself.
+
+- If the account is not on Pro, the browser shows an upgrade page instead
+  of Allow.
+- On a machine without a browser, run `grape login --no-browser`, open the
+  printed address on any device, and paste the address the browser ends up
+  on back into the terminal.
+- `grape whoami` shows the account, `grape logout` removes the sign in from
+  this computer.
+
+The sign in is kept in `~/.config/grape/credentials.json` (on Windows
+`%APPDATA%\grape\credentials.json`), readable by your user only. It renews
+itself and lasts until it goes 90 days unused.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `grape notes list [--folder <id>] [--pinned] [--deleted] [--limit <n>] [--all]` | Notes, newest first |
+| `grape notes search <query>` | Notes that contain a word or phrase |
+| `grape notes get <id>` | One note as markdown (also `read`) |
+| `grape notes create [text] [--file <path>] [--folder <id>] [--pin]` | A new note from markdown |
+| `grape notes append <id> [text] [--file <path>]` | Add to the end of a note |
+| `grape notes replace <id> [text] [--file <path>] [--force]` | Replace the whole note |
+| `grape notes move <id> <folder-id>` | Move a note, or restore one from Recently Deleted |
+| `grape notes delete <id>` | Move a note to Recently Deleted (restorable for 30 days) |
+| `grape folders list` | Every folder with its id and note count |
+| `grape folders create <name> [--parent <id>]` | A new folder |
+| `grape folders rename <id> <name>` | Rename a folder |
+| `grape folders move <id> <parent-id\|root>` | Move a folder |
+| `grape folders delete <id>` | Delete a folder; its notes go to Recently Deleted |
+| `grape tools list` / `grape tools call <name> '<json>'` | The MCP tools, called directly |
+| `grape guides search <question>` | Answers from the help center |
+| `grape guides list` / `grape guides read <slug>` | Help articles, as markdown |
+| `grape plans` | Plans, prices and what each includes |
+| `grape changelog [--platform desktop\|mobile]` | What changed in the latest releases |
+| `grape downloads [--kind desktop\|mobile]` | Download links for every platform |
+
+`grape <command> --help` shows every option.
+
+## Writing notes
+
+Notes are markdown: headings, lists, check lists, tables, links, bold and
+italic. The first line is the title, so start with a heading. A word that
+starts with `#` becomes a tag, and `[[Note title]]` links to another note.
+The text can come from the arguments, a file, or a pipe:
+
+```sh
+grape notes create "# Standup" --folder 1000000000002
+grape notes create --file meeting.md
+pbpaste | grape notes create
+grape notes append 4821930571234 "- Call the printer"
+```
+
+Images, drawings, slide decks and other blocks show up in `grape notes get`
+as lines like `{{grape-block:drawing:4821930571234:0}}`. Keep those lines when
+you `replace` a note, or the block behind them is deleted. `replace` checks
+first and stops if your text would remove one; `--force` removes them.
+
+Changes reach the Grape apps on every device through sync within minutes.
+Locked notes are encrypted on your devices and are never listed or read.
+
+## For scripts and AI agents
+
+Every command takes `--json` and then prints only JSON on stdout. Progress
+and errors go to stderr, so stdout stays clean for a pipe.
+
+```sh
+grape notes search "invoice" --json | jq -r '.notes[].localId'
+grape folders list --json | jq '.folders[] | select(.name == "Work")'
+```
+
+A failure exits with a code you can branch on, and with `--json` it prints
+one line of JSON on stderr:
+
+```json
+{"error":{"code":"signed_out","message":"You are not signed in to Grape.","hint":"Run grape login to sign in."}}
+```
+
+| Exit code | Meaning |
+| --- | --- |
+| 0 | Done |
+| 1 | It failed; the message says why (`pro_required`, `rate_limited`, `tool_error`, `network_error`...) |
+| 2 | The command line was wrong |
+| 3 | No usable sign in: ask the user to run `grape login` |
+
+The account allows 600 note and folder calls an hour. `grape notes list
+--all` pages through 50 notes per call.
+
+## Environment
+
+| Variable | Default | |
+| --- | --- | --- |
+| `GRAPE_ACCESS_TOKEN` | | Use this bearer token instead of the stored sign in |
+| `GRAPE_CONFIG_DIR` | `~/.config/grape` | Where the sign in is kept |
+| `GRAPE_URL` | `https://grape.cool` | The OAuth server and the public API |
+| `GRAPE_MCP_URL` | `https://mcp.grape.cool` | The MCP server |
+| `GRAPE_DEBUG` | | Print stack traces for unexpected errors |
+
+## How it works
+
+- Notes and folders go through Grape's MCP server at
+  `https://mcp.grape.cool`, the one ChatGPT and Claude connect to, over the
+  stateless 2026-07-28 revision of MCP Streamable HTTP. If you would rather
+  connect an MCP client directly, see
+  [Connect ChatGPT and Claude](https://grape.cool/help/connect-chatgpt-and-claude).
+- Signing in is OAuth 2.1 for native apps (RFC 8252): dynamic client
+  registration, a loopback redirect on `127.0.0.1`, PKCE with S256, and the
+  `state` and `iss` checks. Tokens are scoped to the MCP server.
+- Plans, changelog, downloads and guides read the public API at
+  `https://grape.cool/api/v1`, documented at
+  [grape.cool/docs](https://grape.cool/docs).
+
+## Support
+
+Write to [support@grape.cool](mailto:support@grape.cool) or use
+[grape.cool/contact](https://grape.cool/contact).
+
+## Development
+
+```sh
+pnpm install
+pnpm test          # vitest, against a stand in MCP server built on the MCP SDK
+pnpm typecheck
+pnpm build         # dist/cli.js
+pnpm grape -- notes list
+```
+
+Point it at local servers with `GRAPE_URL=http://localhost:4700` and
+`GRAPE_MCP_URL=http://localhost:4702`. Releasing is in
+[docs/RELEASING.md](docs/RELEASING.md).