Raycast Extension

The Teak Raycast extension brings your personal knowledge hub directly into Raycast, enabling ultra-fast capture and search without leaving your keyboard.

Overview

Built specifically for Raycast on macOS, this extension provides keyboard-first access to your Teak vault with three powerful commands.

Technology Stack

Raycast API 1.104+
React components
Raycast Utils
Teak API integration

Platform

macOS only
Raycast required
Keyboard-first workflow
Native macOS integration

Commands

The extension provides three focused commands:

Quick Save

Capture text or links to Teak without leaving your workflow

Paste or type any content
Automatically detects URLs
Instant save with feedback
Duplicate detection
No context switching required

# Default Raycast shortcut (customizable)
⌘ + Space → Quick Save

Perfect for:

Saving links while browsing
Capturing quick notes
Storing URLs from Slack/Email
Recording fleeting thoughts

Search Cards

Find anything in your Teak vault instantly

Full-text search across all cards
Search by content, tags, or metadata
Real-time results as you type
Open cards in Teak web app
Copy card content to clipboard

# Launch search
⌘ + Space → Search Cards

Search capabilities:

Card titles and content
AI-generated summaries
Tags and categories
URLs and metadata

Favorites

Access your saved favorites lightning fast

Browse favorited cards
Instant access to important items
Open in web app or copy
Keyboard navigation

# Access favorites
⌘ + Space → Favorites

Ideal for:

Frequently referenced links
Important notes
Go-to resources
Quick reference materials

Installation

Prerequisites

Install Raycast

Download and install Raycast (free):

# Via Homebrew
brew install --cask raycast

Get API Key

Generate an API key from Teak:

Open Teak Settings
Navigate to API Keys
Click Generate New Key
Copy the key (shown once)

Install Extension

Raycast Store
Developer Mode

Open Raycast Store

Open Raycast (⌘ + Space)
Type “Store”
Press Enter

Search for Teak

Search for “Teak” in the extension store

Install

Click Install and follow the prompts

Configure API Key

Paste your API key when prompted

Clone & Build

# Clone repository
cd apps/raycast

# Install dependencies
bun install

# Build extension
bun run build

Import to Raycast

Open Raycast
Go to Extensions
Click ”+” → Import Extension
Select the raycast directory

Configure

Add your API key in extension preferences

Configuration

API Key Setup

The extension requires an API key to communicate with your Teak account:

Generate Key

In Teak web app:Settings → API Keys → Generate New Key

Add to Raycast

In Raycast:

Open Raycast preferences (⌘ + ,)
Go to Extensions → Teak
Paste your API key
Save

Verify

Test the connection:

# Try Quick Save command
⌘ + Space → Quick Save
# Type something and save

API keys are stored securely in your macOS Keychain. They never leave your device except to authenticate with Teak’s API.

Keyboard Shortcuts

Customize shortcuts for each command:

Open Raycast Preferences
Go to Extensions → Teak
Click on a command
Set your preferred keyboard shortcut

Recommended Shortcuts

Quick Save: ⌥ + ⌘ + S
Search Cards: ⌥ + ⌘ + F
Favorites: ⌥ + ⌘ + D

Development

Setup

# Install dependencies
bun install

# Start development server
bun run dev

# Build for production
bun run build

Project Structure

raycast/
├── src/
│   ├── quick-save.tsx       # Quick Save command
│   ├── search-cards.tsx     # Search command
│   ├── favorites.tsx        # Favorites command
│   ├── lib/
│   │   ├── api.ts           # Teak API client
│   │   └── preferences.ts   # Extension preferences
│   ├── components/
│   │   ├── MissingApiKeyDetail.tsx
│   │   └── SetApiKeyAction.tsx
│   └── __tests__/           # Test files
├── assets/
│   └── icon.png             # Extension icon
└── package.json             # Extension manifest

API Integration

The extension uses the Teak API for all operations:

lib/api.ts

import { getPreferences } from "./preferences";

export async function quickSaveCard(content: string) {
  const { apiKey } = getPreferences();
  
  const response = await fetch("https://api.teakvault.com/cards", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${apiKey}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ content }),
  });
  
  return response.json();
}

Command Implementation

Each command is a separate React component:

quick-save.tsx

import { Action, ActionPanel, Form, showToast } from "@raycast/api";
import { quickSaveCard } from "./lib/api";

export default function QuickSaveCommand() {
  const handleSubmit = async (values: { content: string }) => {
    try {
      await quickSaveCard(values.content);
      await showToast({ title: "Saved to Teak" });
    } catch (error) {
      await showToast({ 
        title: "Save failed", 
        message: error.message 
      });
    }
  };
  
  return (
    <Form
      actions={
        <ActionPanel>
          <Action.SubmitForm onSubmit={handleSubmit} />
        </ActionPanel>
      }
    >
      <Form.TextArea
        id="content"
        title="Content"
        placeholder="Paste or type text, links, or notes..."
      />
    </Form>
  );
}

Features in Detail

Quick Save

The Quick Save command provides instant content capture:

Text
URLs
Mixed

Save quick notes and thoughts:

Remember to check the quarterly reports

Saved as text card
AI summary generated
Searchable immediately

Save web links with automatic metadata:

https://example.com/article

Automatic title extraction
Open Graph metadata
Favicon and preview
Duplicate detection

Save notes with embedded links:

Check out this article: https://example.com
Great insights on productivity

Smart link detection
Preserves context
Full-text searchable

Search Cards

Powerful search with real-time results:

// Search implementation
const { data, isLoading } = useSearch(
  async (query) => {
    return await searchCards(query);
  },
  [searchQuery]
);

Search features:

Instant results as you type
Fuzzy matching
Search across all card types
Filter by favorites, tags, or date
Preview card content
Open in Teak or copy to clipboard

Favorites

Quick access to your starred content:

// Favorites list
const favorites = await getFavorites();

return (
  <List>
    {favorites.map(card => (
      <List.Item
        key={card.id}
        title={card.title}
        actions={
          <ActionPanel>
            <Action.OpenInBrowser url={card.url} />
            <Action.CopyToClipboard content={card.content} />
          </ActionPanel>
        }
      />
    ))}
  </List>
);

Performance

Optimization

The extension is optimized for speed:

Lazy loading: Commands load only when needed
Caching: Recent searches cached locally
Debouncing: Search queries debounced (300ms)
Minimal bundle: ~50KB total size

Response Times

Quick Save: <500ms
Search: <200ms (cached), <1s (new query)
Favorites: <300ms

Error Handling

The extension provides clear error messages:

try {
  await quickSaveCard(content);
} catch (error) {
  if (error.code === "UNAUTHORIZED") {
    showToast({
      style: Toast.Style.Failure,
      title: "Authentication failed",
      message: "Check your API key in extension preferences"
    });
  }
}

Invalid API Key

Error: “Authentication failed”Solution:

Generate a new API key in Teak settings
Update in Raycast preferences
Try again

Network Error

Error: “Failed to connect to Teak”Solution:

Check internet connection
Verify api.teakvault.com is accessible
Check firewall settings

Card Limit Reached

Error: “Upgrade required”Solution:

Upgrade your Teak plan
Delete old cards
Check billing settings

Privacy & Security

Privacy First

API key stored in macOS Keychain
No telemetry or analytics
Direct communication with Teak API only
No third-party services
Open source code

Data Flow

All communication is encrypted (HTTPS) and authenticated with your personal API key.

Publishing

To publish the extension to the Raycast Store:

Prepare

Ensure all metadata is complete:

package.json

{
  "name": "teak-raycast",
  "title": "Teak",
  "description": "Save ideas fast, search your Teak cards...",
  "icon": "icon.png",
  "author": "praveenjuge",
  "categories": ["Productivity"]
}

Build

bun run build

Publish

bun run publish

Follow Raycast’s review process

Troubleshooting

Extension Not Loading

Check Raycast version (requires 1.50+)
Reinstall extension
Check console for errors: ⌘ + ⌥ + I in Raycast
Verify package.json is valid

Commands Not Appearing

Rebuild extension: bun run build
Refresh Raycast: ⌘ + R
Check extension is enabled in preferences
Reinstall if necessary

Slow Performance

Clear Raycast cache
Reduce search result limit
Check network latency
Update to latest version

Roadmap

Planned features for future releases:

Offline Support

Cache recent cards for offline access

Quick Look

Preview cards without opening web app

Templates

Save with predefined templates

Learn More

API Reference

Learn about Teak’s API

Web App

Explore the Teak web application

Raycast

Official Raycast developer docs

Get Raycast

Download Raycast for macOS

Get Started

Core Features

Platforms

Guides

​Overview

Technology Stack

Platform

​Commands

​Installation

​Prerequisites

​Install Extension

​Configuration

​API Key Setup

​Keyboard Shortcuts

Recommended Shortcuts

​Development

​Setup

​Project Structure

​API Integration

​Command Implementation

​Features in Detail

​Quick Save

​Search Cards

​Favorites

​Performance

​Optimization

​Response Times

​Error Handling

​Privacy & Security

Privacy First

​Data Flow

​Publishing

​Troubleshooting

​Roadmap

Offline Support

Quick Look

Tags

Templates

​Learn More

API Reference

Web App

Raycast

Get Raycast

Build docs developers (and LLMs) love

Overview

Commands

Installation

Prerequisites

Install Extension

Configuration

API Key Setup

Keyboard Shortcuts

Development

Setup

Project Structure

API Integration

Command Implementation

Features in Detail

Quick Save

Search Cards

Favorites

Performance

Optimization

Response Times

Error Handling

Privacy & Security

Data Flow

Publishing

Troubleshooting

Roadmap

Learn More