Use Grape from the terminal and your AI agents

Before you start

• A Grape account on Pro, signed in with the same Google account you use in the Grape apps.
• Sync on in the app, since the CLI works with the notes in your account.
• Node.js 20 or later on your Mac, Windows or Linux computer. If node --version finds nothing, install it from nodejs.org.

Install it

Open a terminal and run:

npm install -g @grapecool/cli

That adds the grape command. grape --version says which version you have, and grape --help lists every command. To try it without installing anything, write npx @grapecool/cli where these examples say grape.

Sign in

Run grape login. Your browser opens grape.cool: sign in with Google, check that the page names your account, and choose Allow. The terminal finishes by itself and says which account it signed in to, and grape whoami says it again at any time.

On a computer without a browser, such as a server, run grape login --no-browser, open the address it prints on any device, and after Allow paste the address the browser ends up on back into the terminal.

The sign in stays on that computer and renews itself, so you only do this once.

Try it

Every note and folder has an id, the long number the lists show, and the other commands take it.

grape notes list
grape notes search "standup"
grape notes get 4821930571234
grape notes create "# Call the dentist"
grape notes append 4821930571234 "- Bring the slides"
grape folders list

A note is written in markdown. The first line is its title, so start with a heading. A word that starts with # becomes a tag, and [[Note title]] becomes a note link. The text can also come from a file with --file, or straight from another command: pbpaste | grape notes create makes a note of whatever you copied on a Mac.

Use it with an AI agent

An AI agent that works in your terminal can run grape for you. Install the CLI and sign in once, then ask in your own words:

• "Save a summary of what we did today to my Work folder in Grape."
• "Find my notes about the Q3 plan and tell me what we decided."
• "Add these action items to my Monday standup note."
• "Make a Grape note with the release checklist for this project."
• "Read my Interview with Dana note and draft the follow up email."

The agent learns the commands from grape --help. Every command also prints JSON with --json, which agents read best, and when the sign in has run out the agent sees exit code 3 and asks you to run grape login again.

Ideas for scripts

• Start each day from your template: grape notes create --file ~/daily.md from cron or a shortcut.
• Keep what a command printed: (echo "# Yesterday's commits"; git log --oneline --since=yesterday) | grape notes create.
• Keep a list of every note as JSON: grape notes list --all --json > notes.json.
• Answer a question about Grape with no account: grape guides search "sync not working".

What it can and cannot do

It uses the same twelve tools as the connection for ChatGPT and Claude, with the same limits. A delete moves the note to Recently Deleted, where you can restore it for 30 days. A locked note is never listed, read or changed. It cannot add images or files, edit handwriting notes, or reach the drawings, flashcards, slide decks and other blocks inside a note. grape notes get shows those blocks as placeholder lines, and grape notes replace stops if your new text would remove one. An account can make 600 calls an hour.

When you see the changes

A note the CLI writes reaches your devices the way any synced change does: when the app starts, when you come back to it, every fifteen minutes, or straight away with Sync Now in the Cloud Sync tab of Settings.

Signing out

grape logout removes the sign in from that computer. A sign in that goes unused for 90 days ends on its own, and ending your Pro plan ends it too.