Getting Started

Install

npm install -g @kkarimi/gran
gran --help

If you do not want a global install:

npx @kkarimi/gran --help

The package exposes gran as the executable name.

If you prefer not to use npm at all, each GitHub release also ships standalone archives for macOS arm64, Linux x64, and Windows x64. Extract the archive and run gran (or gran.exe on Windows).

First Run

Create your default Gran setup first:

gran init

That writes:

• ~/.config/gran/config.json
• local support files under ~/.config/gran/

The generated files are intentionally local and editable. They give you a user-level home for config, knowledge-base profiles, and integrations without forcing you to reverse-engineer the JSON shape first.

In an interactive terminal, gran init offers guided setup immediately:

1. connect Granola
2. import meetings into the local archive
3. open the browser workspace by default, or choose the terminal workspace instead

That means gran init is usually enough for the first run.

If you skip the guide or you are running in a non-interactive shell, continue with one of:

gran web

gran web prefers the reusable background-service path, so it will reuse or start the local runtime for you.

Use gran tui later when you want the keyboard-first terminal workspace.

If you do want repo-local config instead, run gran init --project.

Default Surface

Browser Workspace

gran web

This is the normal first-run path. Use it when you want the easiest place to inspect sync state, folders, meetings, and knowledge bases.

Terminal Workspace

gran tui

Use this later when you want a keyboard-first workspace on the same shared local runtime. If you start from gran init, the guided setup can land you here directly.

Headless Local Runtime

gran service start
gran attach
gran service status

Use this when you want the sync loop and local runtime running before you open either browser or terminal UI.

Advanced Alternatives

If you prefer CLI auth instead, store a Granola Personal API key once:

gran auth login --api-key grn_...
gran auth status

If you prefer to reuse the desktop app session, gran auth login imports it from supabase.json.

If you want to verify that the local archive is ready without opening a UI:

gran sync
gran folder list
gran meeting list --limit 10

Common Next Steps

• gran export when you want notes and transcripts in durable local files
• gran kb add ... when you want a saved destination like an Obsidian vault
• gran folder list and gran meeting list when you want quick local verification from the CLI
• gran events --format jsonl --follow when you want to feed another local tool
• Settings -> Advanced only when you want deeper diagnostics or the advanced automation layer

For concrete examples, see Workflows.

Next