A terminal-based CLI tool for interacting with Granola notes and folders. The CLI enables you to list, search, and create notes from the command line.

• List all folders: granola folders
• List/search/filter notes: granola notes
  • Options: --title, --date, --content, --folder
• Show note details and AI summary: granola note <id>
  • Options: --transcript-only, --summary-only, --raw
• Export note content as markdown: granola export <id>
  • Options: --transcript, --all, --raw, --output <directory>
• Create a new note: granola create
• API authentication via local Granola desktop app
• Docker support for containerized usage
• Devcontainer for VS Code development

Choose your preferred setup method:

Prerequisites:

• Node.js 20+
• Granola desktop app (for authentication)

Steps:

git clone <repo-url>
cd granola-cli
npm install
npm run setup     # Builds and links CLI globally

Verification:

granola --version
granola --help

Prerequisites:

• Docker and Docker Compose
• Granola desktop app (for authentication)

Development:

git clone <repo-url>
cd granola-cli
docker compose up --build

Production:

docker compose --profile production up --build -d

Run commands:

# Development
COMPOSE_PROFILE=development docker compose exec granola-cli-dev granola folders
COMPOSE_PROFILE=development docker compose exec granola-cli-dev granola notes

# Production  
COMPOSE_PROFILE=production docker compose exec granola-cli-prod granola folders

Prerequisites:

• VS Code + Dev Containers extension + Docker Desktop

Steps:

1. Open project in VS Code: code .
2. Click "Reopen in Container" when prompted
3. CLI is automatically set up and ready to use

Features:

• 🔧 Complete development toolchain (TypeScript, ESLint, Prettier)
• 🐚 Enhanced terminal (Zsh + Oh My Zsh)
• ⚡ Fast rebuilds with Docker layer caching
• 🔒 Isolated environment

Features include complete development toolchain with enhanced terminal experience.

The CLI automatically reads your access token from the Granola desktop app configuration. The token is read dynamically to handle automatic rotation (tokens refresh every ~24 hours).

macOS Path: ~/Library/Application Support/Granola/supabase.json

Custom Config Path (optional):

export GRANOLA_CONFIG_PATH="/path/to/supabase.json"

📖 For container setup details, see: AUTHENTICATION.md

List folders:

granola folders

List/search/filter notes:

granola notes
granola notes --title "meeting"
granola notes --date 2025-07-01
granola notes --content "project"
granola notes --folder abc123

Show note details and AI summary:

granola note note1                    # Show metadata + AI summary (default)
granola note note1 --transcript-only # Show metadata + transcript only
granola note note1 --summary-only    # Show metadata + AI summary only
granola note note1 --raw             # Show raw content without formatting

Export note content as markdown:

granola export note1                      # Export AI summary as markdown (default)
granola export note1 --transcript         # Export transcript as markdown
granola export note1 --all                # Export both summary and transcript
granola export note1 --raw                # Export raw content without formatting
granola export note1 --output ./my-notes  # Export to custom directory

Create a new note:

granola create

npm install
npm run dev        # Watch mode for development
npm run build      # Compile TypeScript
npm run start      # Run the compiled CLI

Manual Docker commands:

docker build -t granola-cli .
docker run --rm -it \
  -v "$HOME/Library/Application Support/Granola:/granola-config:ro" \
  granola-cli folders

Using npm scripts:

# Development
npm run docker:dev

# Production
npm run docker:prod

# Stop containers
npm run docker:stop

# View logs
npm run docker:logs

# Access shell
npm run docker:shell

Command not found:

1. Run npm run setup to re-link the CLI
2. Check if build was successful with npm run build
3. Verify npm link worked with which granola

Permission errors:

• Use sudo npm link or run the provided setup scripts
• The setup scripts handle permissions automatically

Container issues:

• DevContainer: Rebuild container to trigger postCreateCommand
• Production: Rebuild Docker image to ensure npm link runs

"Not authenticated" error:

• Run ./scripts/get-granola-token.sh on your host machine to get your token
• Set GRANOLA_ACCESS_TOKEN environment variable
• Ensure Granola desktop app is running and you are logged in

Container authentication:

• Use environment variable: GRANOLA_ACCESS_TOKEN="your_token"
• Or mount config directory with correct paths for your OS

📖 Detailed troubleshooting: AUTHENTICATION.md

flowchart TD
    A[User] -->|Runs CLI| B[granola.js]
    B --> C{Authenticated?}
    C -- No --> D[Prompt login via Granola app]
    C -- Yes --> E[Perform Command]
    E --> F[API Request]
    F --> G[Granola Cloud]
    G --> H[Return Data]
    H --> I[CLI Output]

• AUTHENTICATION.md - Complete authentication guide
• DEPLOYMENT.md - Docker deployment and production setup
• .devcontainer/README.md - DevContainer setup and troubleshooting

This project was heavily inspired by the Granola Raycast extension and aims to provide a similar experience in the terminal.