# Teak
> Teak is a personal knowledge hub for saving, finding, and syncing cards. Use the REST API at https://teakvault.com/api/v1, the MCP server at https://teakvault.com/mcp, and bearer auth with OAuth access tokens or teakapi_ API keys.
# Smoother settings navigation
Source: https://teakvault.com/changelog/09-05
- Visiting settings and returning home now keeps your library, search, and unsaved draft ready without repeating full-page loading screens.
- Settings shows available information immediately while individual sections finish loading.
---
# Manage account access in Security
Source: https://teakvault.com/changelog/09-07
- Security in Settings brings your devices, connected apps, and API keys together. Sign out a device or disconnect an app when you no longer need its access.
- After updating Chrome or Safari, sign in once again to reconnect the extension.
- Chrome keeps interrupted saves pending so you can retry them after reconnecting, or discard them from the popup.
---
# More reliable sign-out and app connections
Source: https://teakvault.com/changelog/09-08
- Signing out a device in Security now immediately stops it from reading or saving cards.
- Signing out of desktop, CLI, or Raycast revokes that installation's access. If sign-out fails, you can retry without losing the saved credentials.
- Disconnecting an app or revoking an API key immediately stops its MCP access, including existing connections.
---
# More reliable imports
Source: https://teakvault.com/changelog/09-12
- Canceling an import now stops parsing between batches.
- Archive imports detect changes to the uploaded file during processing.
- Import error reports show short excerpts of failed items to keep large reports manageable.
---
# Simpler setup and sign-in
Source: https://teakvault.com/changelog/09-14
- Setting up Teak locally is now a single command that installs dependencies, provisions an isolated backend, and writes the local configuration.
- Signing in with email works without configuring Google or Apple first. The Google and Apple buttons stay visible and explain clearly when they are unavailable.
- If you self-host Teak with custom addresses for the API or the assistant integration, replace those settings with a single public origin as described in the self-hosting guide. Sign-in keeps using `SITE_URL`.
- The Teak for Safari app is now a native Mac settings window with Settings and About tabs, including wordmark, Early Access badge, and signature from the web settings footer.
---
# API search and favorites move to card listing
Source: https://teakvault.com/changelog/09-16
- The dedicated API search and favorites endpoints are removed. Direct API integrations should use filtered card listing for the same results.
- The CLI, SDK, MCP tools, and Raycast extension already use filtered listing in 1.0.70 and later, so upgrading keeps most setups unchanged.
---
# August 2025
Source: https://teakvault.com/changelog/august-2025
- Teak launched with card saving, search, and a masonry grid for browsing your saved ideas.
- Paid plans arrived for people who need more room than the free tier, with usage limits that behave consistently.
- Search and filters handle large libraries without slowing down, and a command palette gets you to common actions fast.
- Mobile now has dedicated Home and Settings screens, plus a subscription management page.
- The browser extension can automatically save the page you are viewing, and right-click actions let you save links, text, and images without opening Teak.
- Link cards pull in better titles, images, and source details from the pages you save.
- Drag files straight into Teak and watch upload progress while they save.
- File cards can be downloaded directly when you need the original asset.
- Filter your library by card type to narrow things down fast.
- Quote and palette cards are now supported, with color parsing and rich previews.
- Favorite actions feel instant, with card updates showing up right away.
- Select multiple cards at once and clean them up in one pass.
- The browser extension shows clearer save status while pages are being captured.
---
# August 2026
Source: https://teakvault.com/changelog/august-2026
- Image and video cards now load noticeably faster, with your library reusing what it has already downloaded instead of fetching everything again.
- Image-heavy libraries now open with fewer requests, recover a failed preview without reloading the page, and keep video files idle until you interact with them.
- Image uploads are now verified before saving, so broken or mislabeled image files are rejected with a clear error instead of creating a card that never shows a preview.
- iPhone photos and SVG graphics now prepare their previews and colors at the edge, so new cards finish processing noticeably sooner.
- Large image cards gain a mid-size preview, so opening a card no longer downloads the full original.
- Videos and audio scrub smoothly without restarting from the beginning.
- Hovering a card quietly prepares its full preview, so opening a card feels instant.
- Saved-card links, page reloads, and Markdown file uploads now finish reliably across the web app and browser extension.
- The iPhone and iPad apps no longer close immediately on launch, and search, refresh, card opening, and image-heavy libraries load more quickly.
- Continue with Apple now completes sign-in reliably on the web and in Teak for Safari.
- Uploaded PDFs show their first page as the card preview in the grid again.
- New image cards finish preparing their previews and colors noticeably faster, and large exports build quicker and more reliably.
- Document cards now keep their spot in the grid while their preview loads, so other cards no longer jump around.
- Notification banners now keep their icon, message, and close button centered together.
- External apps now show an approve-or-deny screen before they can access your vault.
- Active file types from uploads and imports now download instead of opening as web pages.
- Image cards now wait for a compatible preview before analysis, and temporary empty responses retry later so AI tags and summaries recover without blocking the card.
- Audio recordings made in Chrome and Safari now save as audio cards with the waveform player instead of video cards.
- Large uploads can continue from their completed parts after a temporary interruption instead of restarting from zero.
- Exports can resume after temporary failures, missing image previews repair automatically, and document cards show richer facts such as word, line, heading, slide, and archive counts.
- Image cards now use private, device-sized previews in modern formats for the grid and full-card view, while downloads keep the unchanged original.
- Image cards once again receive automatic summaries and searchable tags after processing.
- File uploads now finish reliably across the web app, browser extension, API, CLI, and MCP.
- Signing in from desktop, the CLI, Raycast, or a browser extension now asks you to approve access before Teak connects the device.
- API keys are limited to 10 active keys per account, with a revoke-all control in Settings if you need to clear every key.
- Automatic image summaries now recover from brief Workers AI capacity shortages instead of failing immediately.
- Teak's homepage now gives a clearer tour of saving, search, automatic organization, capture apps, portable imports and exports, and agent integrations.
---
# December 2025
Source: https://teakvault.com/changelog/december-2025
- Sign in with Apple is now available on mobile.
- Free accounts can now hold up to 200 cards.
- Image saves can automatically pull a color palette for quicker browsing.
- File uploads carry richer details and surface errors more clearly.
- Link and file cards look better on mobile, especially when preview data is limited.
- Tag management and image copy let you organize and reuse saved content faster.
- Paginated search and infinite scroll keep large libraries snappy.
- Thumbnail generation handles SVGs, EXIF orientation, and video frames.
- Loading and verification screens feel less abrupt across the app.
---
# February 2026
Source: https://teakvault.com/changelog/february-2026
- Save cards, search your library, and open favorites directly from Raycast. Duplicate-link checks reduce accidental double saves.
- API keys are now managed from settings with clear revoke and replace flows.
- The desktop app can sign in securely with the same account flow as the web app.
- Desktop keyboard shortcuts make common window actions feel more native.
- Several desktop bugs in card opening and modal behavior were fixed.
- Haptic feedback makes key actions feel more responsive on mobile.
- Loading and error states are clearer when cards take time to appear.
- Touch targets and text styling were improved for easier reading and tapping on mobile.
---
# January 2026
Source: https://teakvault.com/changelog/january-2026
- Search filter pills are easier to use without losing your place, with a Clear All option when text is active.
- Audio and video previews can include captions, making saved media easier to revisit.
- Accessibility polish added better labels and controls across the app.
- SVG elements gained proper titles for screen readers.
- Sitemap and structured data improve discoverability from search engines.
---
# July 2026
Source: https://teakvault.com/changelog/july-2026
- Docs pages can be saved as a PDF or EPUB from the page actions menu.
- The API docs now include a searchable, operation-by-operation reference with schemas and code samples.
- Transparent images in your grid no longer show a gray placeholder icon behind them.
- The desktop app is here. Record audio notes (macOS asks for microphone access the first time), upload files reliably, and sign in through your browser in one step. Signing out of desktop no longer signs you out of Teak on the web.
- Install Teak for Safari from the Mac App Store to save pages directly from the Safari toolbar.
- The browser extension now signs you in through the web app in one step.
- Teak now has a command-line app to save, search, edit, favorite, delete, sync, and list tags from your terminal, with one-step browser sign-in and an Agent Skill for AI assistants.
- Raycast, MCP, and API clients now sign in with your browser in one step, so copying an API key is optional and existing keys keep working.
- The API and MCP server moved to simpler addresses at teakvault.com/api and teakvault.com/mcp. Existing api.teakvault.com links and API keys keep working, so no action is needed.
- The API can now create file cards through direct uploads for images, video, audio, and documents, and card lists can include file names, sizes, and media types. Lists also load reliably across multiple pages, and deleted cards stay hidden from direct lookups.
- MCP clients can now browse cards, look up a card, list tags, sync changes, run bulk edits, and create file-upload links.
- Teak now works as a ChatGPT connector with search and fetch, plus new AI-agent docs pages for easier setup.
- Import and Export now share one place in Settings with a quick tab to switch. Imports show step-by-step progress and explain exactly which items were skipped or failed, and exports show live progress with a countdown to your next weekly export.
- Uploaded PDFs now show a page preview in your grid again, open and preview correctly, and web audio recording works reliably in Chrome.
- Copying from the desktop app now works.
- Saving colors or a color list as a note now creates a palette card again.
- File uploads now report progress accurately and retry brief storage hiccups, so a first drag, drop, or paste is less likely to fail.
- File uploads now support source code, Markdown and MDX, design tokens, ZIP, Office documents, SVG, HEIC, animated GIF, Figma files, and more across web, mobile, desktop, browser extension, API, CLI, and MCP, with a 100 MB limit and safe previews or file facts.
- Markdown and source-file previews now begin loading before you open them, reuse recent downloads, and show a clear loading state on slower connections.
- Writing Markdown notes is faster with clickable tasks, automatic list continuation and indentation, strikethrough controls, and quick actions to open, copy, or edit links—including plain web addresses.
- Desktop sign-in confirmation now includes a clear success indicator.
- Choosing a file in the browser extension now keeps the popup open until the upload finishes or shows an error you can act on.
- Search now clears old cards when a query has no matches, and unfavorited cards disappear immediately from Favorites.
- Settings and sign-in screens now show stable loading states, and managing your subscription opens reliably in Safari and other browsers.
- Saving a web address now reliably creates a link card with a preview, even when it comes in as plain text.
- Signing out on the web now works reliably instead of showing an error screen.
- Large image cards now finish previews, colors, and AI details more reliably, and deleting a card while it is still processing no longer produces follow-up errors.
- Moving between web screens now responds immediately while account data loads.
- Video cards in your library keep a stable height while loading, so the grid no longer jumps when a video appears.
- Hover a video card in your library to preview it muted.
---
# June 2026
Source: https://teakvault.com/changelog/june-2026
- Export your data from Settings on web and desktop. Teak builds a ZIP of your active cards and original files in the background. Track progress, cancel anytime, and download the result. One export per week, available for 7 days.
- Import browser bookmarks and Teak archive files from Settings. Imports skip duplicate links, preserve visible card details, and report created, skipped, and failed totals.
- Import Raindrop bookmarks from Settings: choose your Raindrop CSV and each link arrives with its notes, tags, folder, favorite status, and saved date.
- API keys now have a dedicated management window in Settings with status, copy, revoke, disable, and regenerate controls.
---
# March 2026
Source: https://teakvault.com/changelog/march-2026
- Teak now has a public API, making it easier to connect your own tools and automations.
- MCP clients can connect to Teak to create, search, update, and manage cards remotely.
- Desktop is available as a signed macOS app with native menus, built-in auto updates, and silent background checks.
- Desktop update files are served from the main Teak domain for more consistent delivery.
- Raycast gained Save Clipboard and Save Current Browser Tab commands, plus a refreshed card detail layout.
- Raycast AI can save to Teak, search your cards, and fetch a single card by ID using your existing API key.
- The browser extension adds a save button directly to posts on Instagram, Pinterest, X, Hacker News, and several design news sites, saving the real article URL.
- Saved Instagram and X posts now capture the real text and attached media, so multi-image posts and video tweets render inline.
- Very tall images expand to the full preview width, and you can scroll vertically inside the preview.
- Opening a shared or bookmarked card link with an invalid ID now shows a clear error instead of silently failing.
- Mobile sharing and card deep links open more reliably.
---
# May 2026
Source: https://teakvault.com/changelog/may-2026
- The macOS desktop app was rebuilt with real-time sync, browser sign-in, native menus, drag-and-drop uploads, and automatic updates that show download progress.
- Raycast gained one-shot saving, Save Selected Text, a tag browser with counts, and AI tools for recent cards, tags, and favorites.
- Drag files anywhere in the web and desktop apps to upload in place, with one progress summary per batch.
- The add area is now a focused note with capture actions in the header.
- Mobile is steadier: photos, videos, audio, and documents save again, sign-in is restored on launch, appearance choices persist, and going offline shows a clear retry screen.
- Paging through cards with the API now returns every card instead of sometimes stopping early.
- The API accepts up to 100 cards per bulk request and returns a clear error for empty or oversized batches.
- Link previews now share only a site's domain, never the full saved address, so private links stay private.
- Filtering by a tag with spaces in Raycast now searches that exact tag.
- Install Teak for Safari from the Mac App Store to save the page you are viewing directly from the Safari toolbar.
---
# November 2025
Source: https://teakvault.com/changelog/november-2025
- Card previews handle unusual types more gracefully, and dark mode dialogs are easier on the eyes.
- App-wide error recovery helps you get back on track instead of getting stuck on a broken screen.
- Sign-in, sign-up, and password recovery all run on a cleaner account system with better feedback when something goes wrong.
- Uploading or changing your avatar is more reliable, and you can delete your account from settings.
- Theme selection moved into settings where it is easier to find and change.
- Web and mobile now share the same authentication system, so sign-in feels consistent everywhere.
- Email verification is handled more clearly during account creation.
- PDF and video cards show better previews in the grid.
- More card controls are available right where you need them, and upload flows feel less fragile.
- AI-generated summaries and transcripts are faster, and link previews pull in richer visuals.
- Rate-limit handling and accessibility improvements make the app steadier under load.
---
# October 2025
Source: https://teakvault.com/changelog/october-2025
- The home view can open with cards already loaded, so you spend less time waiting.
- Admins can monitor processing health and retry stuck AI enrichment jobs from a dedicated dashboard.
- Sharing into Teak from other apps expanded, so capture flows are less fragile.
- Saved cards move through a more reliable background pipeline, and fewer items get stuck.
- Link, palette, and fallback previews look better when source data is incomplete.
- Upgrading no longer sends you through a clunky external billing flow. Plan details and billing actions are easier to understand before you pay.
- The card modal is cleaner to read and edit, with improved spacing and layout.
---
# September 2025
Source: https://teakvault.com/changelog/september-2025
- Recording audio on mobile is easier, with permissions and the recording flow handled for you.
- Image cards now show generated thumbnails instead of oversized originals, making image-heavy libraries load faster.
- Manage your subscription from a dedicated billing page, and when you hit your card limit Teak explains what to do next.
- A new Pricing page explains plans and common questions in one place.
- The card grid was rebuilt for smoother scrolling and better responsiveness.
- Card editing was split into dedicated views, making mobile changes easier to manage.
- Link cards have better previews and categorization, so saved inspiration is easier to revisit.
- Teak now runs automatic card classification in the background after you save something.
- The "analyzing" indicator disappears at the right time instead of lingering after work finishes.
---
# Welcome to Teak
Source: https://teakvault.com/docs
Teak is a personal library for links, notes, images, files, and more. Save from any device; AI tags and organizes so you can find things with a short search.
## Get started
Card types, search, AI enrichment, and sync.
Native macOS app with automatic updates.
iOS app with share sheet and voice notes.
One-click save from Chrome, Safari, Edge, and more.
Save and search without leaving the keyboard.
Manage cards from your terminal.
Bookmarks, Raindrop, or a Teak archive.
Download a portable ZIP of your library.
HTTP API for cards, uploads, and sync.
OpenAPI operation pages with schemas and samples.
MCP, CLI, and Agent Skill for AI tools.
Run the monorepo locally.
Run Teak on your own deployment.
## What you can save
| Type | Examples | Auto-features |
| --- | --- | --- |
| Text | Notes, decisions | Full-text search |
| Link | Articles, tools, references | Screenshot, metadata |
| Image | Screenshots, mockups | Color palette |
| Video | Tutorials, clips | Thumbnails |
| Audio | Voice memos | Transcription |
| Document | PDFs and files | Thumbnail previews |
| Palette | Color swatches | Hex values |
| Quote | Passages with source | Source context |
## Help
Contact and bug reports.
How we handle your data.
Rules for using Teak.
---
# Teak for AI Agents
Source: https://teakvault.com/docs/ai-agents
Teak gives AI agents a private memory layer for saved links, notes, files, tags, and design references. Agents can use the hosted MCP server at `https://teakvault.com/mcp`, the REST API at `https://teakvault.com/api/v1`, or the command-line app, with browser OAuth or `teakapi_` API keys for authentication.
## What can agents do with Teak?
Agents can save new cards, search existing cards, get a card by ID, list tags, sync changes, run bulk updates, favorite or delete cards, and create upload URLs for file cards. The MCP server and REST API share the same card operations, so behavior is consistent across tools. This mirrors the tool set in the [Raycast extension](/docs/raycast#ai-tools) and the [MCP server](/docs/mcp#available-tools).
## How do I connect Claude?
```bash
claude mcp add --transport http teak https://teakvault.com/mcp
```
Start the MCP connection in Claude and complete browser sign-in when prompted. API keys also work for clients that let you set an `Authorization: Bearer ` header.
## How do I connect ChatGPT or Deep Research?
Use `https://teakvault.com/mcp` as the remote MCP server URL. Teak exposes the plain `search` and `fetch` tools expected by ChatGPT connectors:
- `search` finds matching cards and returns IDs, titles, and Teak app URLs.
- `fetch` opens a specific card and returns readable text plus metadata.
## How do I use the REST API?
Use the production base URL `https://teakvault.com/api/v1`. See the [API docs](/docs/api) for the full base URL list, authentication, endpoints, and error format — that page is the source of truth for the REST contract.
## What should coding agents read first?
Load these URLs in order before calling Teak tools. Prefer `.md` mirrors when
you need the full page body without HTML chrome.
- `https://teakvault.com/llms.txt` for the compact documentation map
- `https://teakvault.com/llms-full.txt` for the full docs context
- `https://teakvault.com/docs/api.md` for the REST API contract
- `https://teakvault.com/reference` for the interactive OpenAPI reference
- `https://teakvault.com/docs/mcp.md` for MCP setup and tools
- `https://teakvault.com/.well-known/mcp.json` for remote MCP discovery metadata
- `https://teakvault.com/agent-readability.json` for the machine-readable docs surface map
## Can agents use the command line?
Yes. Install the Teak CLI and sign in:
```bash
npx teak-cli@latest login
```
Then use commands such as:
```bash
teak cards search design
teak cards create "https://teakvault.com"
teak tags
```
## Is there an Agent Skill?
Yes. Teak ships a public Agent Skill for assistants that support skills-based workflows. Use it when an agent needs to save, search, retrieve, update, favorite, delete, or sync Teak cards through the CLI, API, SDK, or MCP server.
Install it from [Skills.sh](https://skills.sh/praveenjuge/teak):
```bash
npx skills add praveenjuge/teak --skill teak
```
---
# API
Source: https://teakvault.com/docs/api
Teak provides a public REST API for saving, querying, and syncing cards. Use this guide for integration decisions and the generated reference for every operation, field, schema, and code sample.
Explore the complete OpenAPI contract and samples in curl, JavaScript, and Python.
Connect an AI client to Teak through its remote MCP server.
## Base URLs
| Environment | REST API |
| --- | --- |
| Production | `https://teakvault.com/api/v1` |
| Local development | `http://localhost:3001/api/v1` |
The machine-readable OpenAPI document is available at `https://teakvault.com/api/openapi.json`.
## Authentication
Every API request uses a bearer token in the `Authorization` header.
:::warning[Keep secrets out of logs]
Never commit `teakapi_` keys or paste them into public issue trackers. Rotate a key immediately if it leaks.
:::
**API key**
Generate a long-lived `teakapi_` key in Teak Settings. Each account can have
up to 10 active keys, and new keys can be created at most five times per
minute. Use **Revoke all keys** if you need to clear every key, including any
that no longer appear in the list.
```bash
Authorization: Bearer teakapi_secret_live_a1b2c3d4_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
```
**OAuth**
Browser-login clients can send an OAuth access token. Access tokens expire after one hour and should be refreshed by the client.
## Create your first card
```bash curl
curl https://teakvault.com/api/v1/cards \
--request POST \
--header "Authorization: Bearer $TEAK_API_KEY" \
--header "Content-Type: application/json" \
--header "Idempotency-Key: first-card" \
--data '{
"content": "# Project notes\n\nKeep the original spacing.",
"cardType": "text",
"tags": ["project"]
}'
```
```js JavaScript
const response = await fetch("https://teakvault.com/api/v1/cards", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.TEAK_API_KEY}`,
"Content-Type": "application/json",
"Idempotency-Key": "first-card",
},
body: JSON.stringify({
content: "# Project notes\n\nKeep the original spacing.",
cardType: "text",
tags: ["project"],
}),
});
```
Read the Teak API guide and generated reference. Use my bearer token to list
my newest 10 cards, then summarize their titles and tags.
## Create behavior
`cardType` is optional. Set it to `text` to preserve raw Markdown exactly, even when the content looks like a URL, quote, or color. When omitted, Teak automatically detects links, quotes, and palettes.
A create response includes the new `cardId` and its Teak app URL. See **Create Card** in the [API Reference](/reference) for the complete request and response schemas.
## Upload files
File cards use a direct upload flow, so large bytes never pass through the REST API.
1. **Create an upload**
Send the file name, media type, and size to `POST /v1/uploads`.
2. **Upload the bytes**
`PUT` the file to the returned presigned URL and retain its `ETag` response header.
3. **Create the card**
Send the returned `fileKey`, retained `fileEtag`, and file metadata to `POST /v1/cards`.
Files can be up to 100 MB. Uploaded `.md` and `.markdown` files become editable text cards, must contain valid UTF-8, and are limited to 512 KiB. `.mdx` remains a document.
Supported uploads include common image, audio, video, source, design-token, document, archive, and Figma formats. The [API Reference](/reference) is the canonical source for accepted fields and validation responses.
## Reliable requests
| Prop | Type | Default | Description |
| - | - | - | - |
| `X-Request-Id?` | `response header` | - | Returned for support and log correlation. |
| `Idempotency-Key?` | `request header` | - | Safely retries card creation and bulk operations without duplicating work. |
| `RateLimit-Limit?` | `response header` | - | Appears with Remaining, Reset, and Retry-After rate-limit headers. |
Bulk operations accept up to 100 items. Cursor-based listing and the card changes endpoint are available for integrations that need complete pagination or incremental sync.
## Endpoint overview
| Route | Purpose |
| --- | --- |
| `/v1/cards` | Create or list cards |
| `/v1/uploads` | Start a direct file upload |
| `/v1/cards/bulk` | Create or update multiple cards |
| `/v1/cards/changes` | Read incremental card changes |
| `/v1/tags` | List tags |
| `/v1/cards/:cardId` | Read, update, or delete one card |
| `/v1/cards/:cardId/favorite` | Favorite or unfavorite one card |
See `/openapi.json` or the [API Reference](/reference) for methods, parameters, schemas, and response examples.
## Search and favorites
Search and favorites are filtered card listings. `GET /v1/cards` supports
`q`, `type`, `tag`, `sort`, `createdAfter`, `createdBefore`, `limit`,
`cursor`, `favorited`, and `include`:
- Search: `GET /v1/cards?q=design&include=content,metadata`
- Favorites: `GET /v1/cards?favorited=true&include=content,metadata`
The `include=content,metadata` pair returns full-card fields. The list
response is paginated (`items` plus `pageInfo`).
The dedicated `GET /v1/cards/search` and `GET /v1/cards/favorites` routes were
removed in Teak 1.0.70 and now return `404`. The CLI, SDK, MCP tools, and the
Raycast extension use the list endpoint since 1.0.70, so upgrading is the
migration for most integrations.
Image card responses include intentionally different URLs: `thumbnailUrl`
is the optimized grid rendition, `compactUrl` is a smaller rendition for
compact lists, `placeholderUrl` is a tiny loading placeholder, `detailUrl` is
the optimized full-card rendition, and `fileUrl` remains the signed original
used for downloads. These URLs are temporary bearer credentials; clients
should consume them as returned instead of storing or modifying them.
## Errors
Errors keep a stable `{ code, error }` shape and can also include `requestId`, `details`, or `retryAt`.
```json
{
"code": "INVALID_INPUT",
"error": "Body must include `content` or `url`"
}
```
Use the returned request ID when contacting [Support](/docs/support). For MCP tool contracts and JSON-RPC examples, continue to the dedicated [MCP guide](/docs/mcp).
## Check for a saved URL
`GET /v1/cards/duplicate?url=` accepts the same bearer credentials as other card endpoints. It checks the exact URL against your non-deleted cards and returns `{ "cardId": "..." }`, or `{ "cardId": null }` when no match exists. The URL must use HTTP or HTTPS and be at most 8,192 characters. Invalid input returns 400; invalid or revoked credentials return 401.
## Revoke an OAuth credential
Native OAuth clients can send a form-encoded `POST` to the Convex site origin at `/api/oauth/revoke`, with `client_id` and `token` (an access or refresh token). Revocation invalidates the presented credential pair for that client. Unknown or already revoked tokens return 200, as do successful revocations. This endpoint does not accept API keys. Use **Security** → **Connections** in Settings to revoke every connection for an app.
Native OAuth clients can read the authenticated account with `GET /api/oauth/userinfo` on the Convex site origin. Send the OAuth access token as a bearer token. The response contains `sub`, `email`, and `name`; invalid or revoked credentials return 401. API keys are not accepted by this endpoint.
---
# Command Line
Source: https://teakvault.com/docs/cli
The Teak CLI lets you save, search, favorite, update, and delete cards without leaving your terminal.
## Install
```bash npm
npm i -g teak-cli
```
```bash bun
bun add -g teak-cli
```
```bash npx
npx teak-cli@latest --help
```
After installing globally, the `teak` command is available on your PATH.
## Authentication
**Browser sign-in**
Run:
```bash
teak login
```
Teak opens your browser to authorize the CLI. Approve the request on the
consent screen, then return to the terminal. Existing CLI credentials stay
valid until you sign out or disconnect the app.
**API key**
Set `TEAK_API_KEY` to skip interactive sign-in in scripts and CI:
```bash
TEAK_API_KEY=teakapi_... teak ls --json
```
Generate and manage API keys in Teak Settings → **Manage API Keys**.
```bash
teak logout
```
`teak logout` revokes this installation's browser sign-in before removing stored
credentials from your machine. If Teak cannot be reached, credentials stay saved
so you can retry. Other CLI installations remain connected. To disconnect them
all, use **Settings → Security → Connections**. API keys remain managed under
**Security → API keys**.
## Commands
```bash
teak add "A note from the terminal" --tags research
teak add --url https://example.com --tags research,web
teak add --file ./screenshot.png --notes "Inspiration" --tags inspiration
teak add --file ./component.tsx --tags source
teak ls
teak search "blue buttons"
teak cards get
teak cards update --tags design,reference
teak fav
teak rm
teak tags
```
`teak add` also accepts a bare URL or file path as the positional argument (for
example `teak add https://example.com`) — the CLI detects whether it's text,
a URL, or a file. Use `--url` / `--file` when you want to be explicit or when
scripting.
File uploads support source and design-token files, Markdown and MDX, ZIP archives, PDF and Office documents, SVG, HEIC, animated GIF, WebM/MP4, Figma `.fig`, and common image/audio formats. `.md` and `.markdown` files become editable text cards, must be valid UTF-8, and are limited to 512 KiB; `.mdx` remains a document. Other supported files allow up to 100 MB.
Text passed to `teak add`, including standard input, is stored as raw Markdown exactly as submitted. Text cards have a 512 KiB UTF-8 limit.
### Getting help
Run any command with `--help` to see available options:
```bash
teak --help
teak add --help
teak search --help
```
## Output Format
By default, commands print human-readable output. Add `--json` to any command for machine-readable JSON, useful for piping into `jq` or other tools:
```bash
teak search "buttons" --json | jq '.items[].url'
```
## Troubleshooting
- Confirm the package installed globally: `npm ls -g teak-cli`
- Make sure your npm global bin directory is in your `PATH`.
- Check your internet connection.
- Try again in case the local callback port was already in use.
- As a fallback, use `TEAK_API_KEY` with a key from Settings.
- Run `teak login` to refresh your session.
- If using `TEAK_API_KEY`, confirm the key is still active in Teak Settings.
Reach out via [Support](/docs/support).
---
# Desktop App (macOS)
Source: https://teakvault.com/docs/desktop
Teak Desktop gives you a native macOS app with automatic updates and the same real-time sync as web and mobile.
macOS Apple Silicon
## Requirements
- macOS 13.0 or newer
- Apple Silicon Mac (M1, M2, M3, or newer)
- Internet connection for sign-in and sync
## Install
1. **Download**
Download the latest macOS build from [GitHub Releases](https://github.com/praveenjuge/teak/releases/latest).
2. **Open the disk image**
Open the `.dmg` file.
3. **Install**
Drag **Teak.app** to **Applications**.
4. **Launch**
Launch Teak from Applications.
## First Launch Security Checks
Teak desktop releases are signed and notarized.
If Gatekeeper blocks launch:
1. **Open Privacy & Security**
Open **System Settings → Privacy & Security**.
2. **Allow Teak**
Find the Teak block message and choose **Open Anyway**.
3. **Relaunch**
Relaunch Teak.
## Sign In
Desktop sign-in opens a secure browser-based authentication window. Approve access
on the consent screen, then the app returns you automatically after login. The
desktop app keeps its own session, so signing out on desktop does not sign you
out of Teak in your browser.
## Teak Menu
The **Teak** menu in the macOS menu bar exposes these actions:
| Item | What it does |
| ---------------------- | ------------------------------------------------------------------------ |
| **About Teak** | Shows the installed version, copyright, and app icon |
| **Check for Updates…** | Manually checks for new versions and shows a notification while checking |
| **Settings…** | Opens the Settings panel (account info, API keys, billing) |
| **Log Out** | Signs you out and returns to the login screen |
## Settings
Open **Teak menu → Settings…** to manage your account:
- **Account**: View your email address and card count.
- **Upgrade / Billing**: Upgrade to Pro or open the customer portal to manage your subscription.
- **API Keys**: Generate API keys for the [Teak API](/docs/api) and [Raycast extension](/docs/raycast).
- **Import/Export Data**: [Import](/docs/import) bookmarks, a Raindrop CSV, or a Teak archive, and start, cancel, and download a portable [data export](/docs/export).
- **Appearance**: Switch between **Auto**, **Light**, and **Dark** themes. Auto follows your macOS system appearance.
- **Sign Out**: Ends your desktop session and returns to the login screen.
- **Delete Account**: Opens `app.teakvault.com/settings` in your browser to complete account deletion.
## Auto Updates
Teak checks for updates on each launch via GitHub Releases.
- If an update is available, you'll see a prompt asking whether to download now or later.
- During download, a macOS notification and a percent badge on the Dock icon show progress.
- After download completes, you'll see a prompt to restart now or later to install the update.
- If update checks fail (for example network outage), Teak continues running and retries on next launch.
## Manual Update / Recovery
If you need to update manually or recover from a failed install:
1. **Quit**
Quit Teak.
2. **Download**
Download the latest release from [GitHub Releases](https://github.com/praveenjuge/teak/releases/latest).
3. **Replace**
Replace **Teak.app** in Applications.
4. **Relaunch**
Relaunch Teak.
## Rollback
If a release is unstable:
1. **Download prior release**
Download the prior stable release from GitHub Releases.
2. **Replace**
Replace **Teak.app** in Applications with that version.
3. **Relaunch**
Relaunch Teak.
Your account data stays in Teak backend storage and local session state is preserved unless you sign out.
## Troubleshooting
- Check your network connection.
- Confirm your system clock is correct.
- Retry after a minute in case of a temporary authentication issue.
- Relaunch the app and wait for the update check.
- Confirm GitHub Releases is reachable from your network.
- On a very old build, install the latest release manually from GitHub.
Reach out via [Support](/docs/support).
---
# Development Guide
Source: https://teakvault.com/docs/development
**Prerequisites:** Git plus Bun and Node.js at the versions pinned in `package.json` (`packageManager` and `engines.node`). Setup validates both and refuses to run on the wrong toolchain.
## Quick Start (local)
1. **Clone the repository**
```bash
git clone https://github.com/praveenjuge/teak.git
```
2. **Move into the project**
```bash
cd teak
```
3. **Provision the local stack**
```bash
bun run setup
```
Setup installs dependencies, provisions an isolated Convex development deployment, and derives the local env files. It needs no production credentials. For another surface, pass `--target` (see below).
4. **Verify readiness**
```bash
bun run doctor
```
5. **Start the stack**
```bash
bun run dev
```
The web app and documentation open in your default browser once both are ready.
## Access Points
- Web App: http://localhost:3000
- Public API: http://localhost:3001/api/v1
- MCP Endpoint: http://localhost:3001/mcp
- Convex Dashboard: opens after `bunx convex dev`
- Mobile: Expo Go or simulator
- Extension: Chrome dev mode
- Safari Extension: Xcode
- Docs: http://localhost:3001
## Project Layout
- teak/
- apps/
- web/ Next.js frontend (app router, shadcn/ui)
- mobile/ Expo React Native
- desktop/ Electron desktop app (React)
- extension/ Chrome extension (Wxt)
- safari-extension/ Native macOS Safari extension app
- raycast/ Raycast extension
- cli/ npm command line client
- docs/ Documentation site (Blume)
- files-worker/ Cloudflare Worker for file delivery and processing
- .agents/
- skills/ Agent Skills for skills.sh
- packages/
- convex/ Convex backend
- ai/ AI metadata helpers
- card/ Card mutations/queries
- workflows/ AI pipeline orchestration
- ui/ Shared UI components and hooks
- files-protocol/ Shared Worker operation contracts
- tests/ Cross-surface Playwright journeys
- turbo.json Turborepo pipeline config
- package.json Root package + workspaces
## Tech Stack
| Layer | Technology |
| ---------- | ------------------------------------------------- |
| Backend | Convex (real-time DB + serverless) |
| Web | Next.js, React, TypeScript, TailwindCSS |
| Mobile | Expo React Native |
| Extensions | Wxt (Chrome), native Safari Web Extension (macOS) |
| Auth | Better Auth |
| UI | shadcn/ui + Radix |
| AI | Cloudflare Workers AI |
| Billing | Polar |
| Testing | Bun (unit), Playwright (E2E) |
| Monorepo | Turborepo |
| Docs | Blume |
## Core Commands
```bash
bun run setup # First run: install deps + provision Convex + write local env
bun run setup --target desktop --convex local --json # Per-target setup with a machine-readable report
bun run doctor # Validate the environment (--json --target --profile for agents)
bun run dev # Web + Convex backend (bun run dev --help for targets)
bun run dev web --headless # Non-interactive output for agents and CI
bun run dev --all # All services (legacy alias: bun run dev:all)
bun run smoke:web # End-to-end local session check (needs the stack running)
bun run audit:env # Environment contract + local dotenv audit
bun run dev convex # Convex backend only (alias: bun run dev:convex)
bun run dev web # Next.js web (alias: bun run dev:web)
bun run dev mobile # Expo mobile (alias: bun run dev:mobile)
bun run dev desktop # Electron desktop (alias: bun run dev:desktop)
bun run dev extension # Chrome extension (alias: bun run dev:extension)
open apps/safari-extension/teak-safari.xcodeproj # Safari extension
bun run dev raycast # Raycast extension (alias: bun run dev:raycast)
bun run dev docs # Docs site (alias: bun run dev:docs)
bun run build # Production build (all)
bun run build:extension # Package Chrome extension
bun run build:raycast # Build Raycast extension
bun run lint && bun run typecheck
bun run test # Unit tests (turbo; test:unit / test:edge for Convex splits)
bun run verify # typecheck + lint + test (affected)
bun run check # Quality report (Ultracite)
bun run fix # Auto-fix issues
bun run pre-commit # Pre-commit checks
bun run publish:raycast # Publish to Raycast store
bun run clean # Clear Turborepo caches
```
## Supported Targets and Limitations
`bun run setup --target ` provisions one surface. Every target except `e2e`
works with zero copied credentials.
| Target | Needs | Limitations |
| --- | --- | --- |
| `web` | Convex deployment | None; the default path |
| `docs`, `cli` | Nothing beyond install | No Convex provisioning |
| `desktop`, `extension` | Convex deployment | Env files derive `VITE_*` aliases automatically |
| `mobile-simulator` | Convex deployment | iOS simulator uses loopback; Android emulators need `10.0.2.2` instead of `localhost` |
| `mobile-device` | Convex deployment, LAN | The host must be LAN-reachable; doctor reports the address or an actionable diagnostic |
| `files-worker` | `bun run sync:cloudflare-dev` afterwards | Worker secrets are owned by the sync command, not setup |
| `e2e` | Production credentials | Not provisioned by setup; see `packages/tests/README.md` |
Linked git worktrees get deterministic ports and a namespace; pair them with
`--convex cloud` for an isolated cloud development deployment so two
checkouts never collide. iOS simulators, device builds, Xcode, and Safari
stay on macOS.
## Reporting Setup Problems
Paste the redacted JSON report with your issue. It contains check names and
remediations but never secret values:
```bash
bun run doctor --target web --profile local --json
```
## Setup Checklist
### Convex + Better Auth
1. **Run setup**
```bash
bun run setup
```
Setup installs dependencies, provisions an isolated Convex development deployment, sets the local `SITE_URL`, pushes backend code, and derives `apps/web/.env.local` from the active deployment. Re-running it is a no-op.
2. **Set the Better Auth signing secret**
```bash
bunx convex env set BETTER_AUTH_SECRET=$(openssl rand -base64 32)
```
3. **Start the backend**
```bash
bunx convex dev
```
`BETTER_AUTH_SECRET` signs sessions (set once per environment). `SITE_URL` must match your Next.js origin; setup configures the local default. `CONVEX_SITE_URL` is the `.site` domain assigned by Convex—copy it from the dashboard.
Google and Apple sign-in are optional locally. Without their credentials, email sign-in works normally and the social buttons report that the provider isn't configured.
### Public API and MCP
The public REST API, MCP endpoint, discovery routes, OpenAPI spec, and SDK live in `packages/convex`. Start Convex to serve the HTTP routes, then use the docs dev proxy for local API and MCP URLs.
Example:
```bash
bun run dev:convex
```
The docs dev server proxies `/api`, `/mcp`, and OAuth protected-resource metadata to the Convex dev deployment. That gives local docs, examples, and smoke tests the same path shape as production: `/api/v1` and `/mcp`.
### MCP Registry
The repo includes `server.json` for the MCP registry under the `com.teakvault/mcp` namespace. Publishing is manual because the namespace requires DNS verification for `teakvault.com`:
```bash
npm install -g mcp-publisher
mcp-publisher login dns
mcp-publisher publish
```
Follow the CLI prompt to add the DNS TXT record, then publish once verification passes.
### Environment Variables
See **[Self-Hosting → Environment settings](/docs/self-hosting#detailed-environment-reference)** for every env var required across web, mobile, extension, and the Convex backend.
Optional local overrides: `TEAK_DEV_APP_URL` (default: `http://localhost:3000`), `TEAK_DEV_API_URL` (only needed when your Convex dev site differs from the repo default), `TEAK_DEV_DOCS_URL` (default: `http://localhost:3001`).
---
# Export Your Data
Source: https://teakvault.com/docs/export
Teak can prepare a portable ZIP archive of your active cards and the original files attached to them. Exports are available from Settings on the web app and desktop app.
:::note[Exports are read-only]
Starting an export does not change, delete, or move anything in your Teak library.
:::
## Start an Export
1. **Open Settings**
Open Teak on web, or open the desktop app and choose **Teak -> Settings...** from the macOS menu bar.
2. **Open Export**
In Settings, find **Export Data** and choose **Manage**.
3. **Start export**
Choose **Start export**.
4. **Wait for preparation**
Keep working while Teak prepares the archive in the background.
5. **Download**
When the export is ready, choose **Download archive**.
You can cancel an export while it is still preparing. Canceled and failed exports do not count toward your weekly export limit.
## What the Archive Includes
Each export is a ZIP file with this layout:
```text
manifest.json
cards.json
files/
```
| File or folder | What it contains |
|---|---|
| `manifest.json` | Export version, schema version, creation time, expiry time, and counts for cards and files. |
| `cards.json` | Your active cards in a portable JSON format. |
| `files/` | Original uploaded files that were available when the archive was created. |
Each card entry can include:
- Card ID, type, content, URL, notes, tags, and favorite status
- Created and updated timestamps
- Visible palette colors
- A file reference when the original file was included
Text cards export their canonical Markdown content only. If a text card originally came from an uploaded Markdown file, that source attachment is intentionally excluded; importing the new archive recreates it as a text-only card.
## What Is Not Included
Exports are intentionally focused on your portable library content. They do not include:
- Cards currently in trash
- AI tags, summaries, transcripts, or generated enrichment fields
- Generated thumbnails, screenshots, favicons, or preview media
- Account, billing, API key, session, or source metadata
- Internal processing state
If an original file cannot be read after retrying, Teak still includes the card in `cards.json` and omits only that file. The export dialog shows how many files were unavailable.
## Limits and Availability
| Limit | Details |
|---|---|
| Frequency | One successful export every 7 days. |
| Active jobs | One export can prepare at a time. |
| Download window | Ready archives stay available for 7 days. |
| Library size | Exports support up to 10,000 active cards or an estimated 5 GB archive. |
If your latest export is still available, download it from **Settings -> Export Data -> Manage**. After it expires, you can start a new export when your weekly quota allows it.
## Troubleshooting
You recently completed an export. Wait for the shown time, then start another one.
Open **Export Data** and try again. Failed exports do not count toward the weekly limit.
The archive still includes those cards in `cards.json`, but their original files were unavailable when the export was built.
If your library is over the export limit, delete unneeded cards or permanently remove old trash items, then try again.
---
# Browser Extensions
Source: https://teakvault.com/docs/extension
Teak for Safari saves the page you are viewing in one click. The Chrome extension adds richer capture options for images, links, selected text, and supported social media posts.
:::note[Safari vs. Chrome feature set]
Teak for Safari is intentionally focused on one-click page saving from the
toolbar. The context menu, inline social-media save buttons, and other capture
options on this page are Chrome/Chromium-only.
:::
## Install
**Chrome**
1. **Open the Chrome Web Store**
Open the [Teak extension](https://chromewebstore.google.com/detail/teak/negnmfifahnnagnbnfppmlgfajngdpob) in the Chrome Web Store.
2. **Add the extension**
Click **Add to Chrome**, then confirm by clicking **Add extension**.
3. **Sign in**
Click the Teak icon in your Chrome toolbar to sign in.
**Safari**
1. **Install from the Mac App Store**
Install [Teak for Safari](https://apps.apple.com/us/app/teak-for-safari/id6770003409?mt=12) from the Mac App Store.
2. **Enable the extension**
Open the app once, then enable the Teak extension in Safari Settings.
3. **Sign in and save**
Click the Teak icon in the Safari toolbar and choose **Sign in**. Teak for Safari opens so you can approve **Teak Safari** in your browser. Return to the toolbar to save the current page.
**Edge**
1. **Open the Chrome Web Store**
Open the [Teak extension](https://chromewebstore.google.com/detail/teak/negnmfifahnnagnbnfppmlgfajngdpob) in the Chrome Web Store.
2. **Allow other stores**
Edge will prompt you to allow extensions from other stores — accept it.
3. **Add the extension**
Click **Add to Chrome**, then confirm in the Edge dialog.
4. **Sign in**
Click the Teak icon in your Edge toolbar to sign in.
**Brave / Arc / other Chromium**
1. **Open the Chrome Web Store**
Open the [Teak extension](https://chromewebstore.google.com/detail/teak/negnmfifahnnagnbnfppmlgfajngdpob) in the Chrome Web Store.
2. **Add the extension**
Click **Add to Brave** (or your browser's equivalent), then confirm.
3. **Sign in**
Pin the Teak icon to your toolbar and click it to sign in.
The Chrome extension works in Chrome and any Chromium-based browser (Edge, Brave, Arc, etc.). Teak for Safari is a native macOS Safari extension app.
## Safari Extension
Clicking the Safari toolbar extension signs you in when needed and saves the current page URL to Teak when you are signed in.
## Auto-Save on Open
When you open either extension popup, Teak automatically saves the current page. The popup shows whether the page was saved, was already in your library, or cannot be saved.
In Chrome and Chromium browsers, choose **Upload file** in the popup to save a supported local file up to 100 MB.
## Chrome and Chromium Features
### Context Menu
Right-click anywhere on a page to access quick-save actions:
| Menu item | What it saves |
| ---------------------- | -------------------------------------------------- |
| **Save Page to Teak** | The current URL |
| **Save Text to Teak** | The selected text (creates a text card) |
| **Save Asset to Teak** | A safely downloadable image, video, audio, or file |
Context menu saves are available on standard web pages. Teak does not attempt to download local, private-network, `file:`, or `blob:` URLs; use **Upload file** when you own a local file.
### Social Media Inline Save Buttons
On supported sites, Teak injects a save button directly into each post or story. You can save individual items without leaving the feed.
| Platform | Supported content |
| ------------------------------------------------------ | ----------------------------------------------------------------------------- |
| [instagram.com](https://www.instagram.com) | Posts and Reels |
| [pinterest.com](https://www.pinterest.com) | Pins |
| [x.com](https://x.com) | Posts (tweets) — saved with tweet text, author, and attached images or videos |
| [news.ycombinator.com](https://news.ycombinator.com) | Story links (saves the outbound article URL) |
| [sidebar.io](https://sidebar.io) | Story links |
| [webdesignernews.com](https://www.webdesignernews.com) | Story links |
| [heydesigner.com](https://heydesigner.com) | Story links |
Inline save buttons appear automatically once you are signed in to the extension. Each saved post is deduplicated — saving the same post twice will not create a duplicate card.
### Free Tier Limit
When you reach your free plan card limit, the Chrome extension popup shows an upgrade prompt instead of saving. Click **Upgrade to Pro** to open Teak Settings.
## Sign In
In Safari, choose **Sign in** to open Teak for Safari and approve **Teak Safari** in your browser. Your connection stays signed in across restarts. After updating from the previous sign-in experience, connect once again.
Manage Safari access from Teak Settings → **Security** → **Connections**. Disconnect **Teak Safari** to revoke access across your Safari installations immediately. Signing out inside Safari disconnects that installation. If you are offline, reconnect to the internet and retry sign-out.
In Chrome and Chromium-based browsers, choose **Sign in** and approve **Teak Chrome** in the browser sign-in window. After updating from the previous sign-in experience, connect once again.
Manage Chrome access from Teak Settings → **Security** → **Connections**. Disconnect **Teak Chrome** to revoke access across your Chrome installations. Signing out inside the extension disconnects only that installation. If a save needs you to reconnect, the extension keeps it pending so you can retry it after signing in. You can also discard pending saves from the popup.
## Troubleshooting
- Check that you are signed in at [app.teakvault.com](https://app.teakvault.com).
- Reload the tab you are trying to save and try again.
- Make sure you are signed in to the extension.
- Reload the page after it fully loads.
- Verify the extension is enabled in `chrome://extensions`.
- Inline buttons appear only on the supported sites listed above.
Reach out via [Support](/docs/support).
---
# Features
Source: https://teakvault.com/docs/features
## Card types
Eight types cover common save workflows. Each gets automatic processing and a rich preview.
| Type | What you save | Auto-features |
| --- | --- | --- |
| **Text** | Notes, decisions, feedback | Full-text search |
| **Link** | Articles, Dribbble shots, tools | Metadata, screenshot, preview |
| **Image** | Screenshots, mockups, photos | Color palette extraction |
| **Video** | Tutorials, animations, clips | Inline player, thumbnails |
| **Audio** | Voice memos, recordings | Transcription |
| **Document** | PDFs, Office files, source, Markdown, ZIP, and design files | Adaptive previews and file facts |
| **Palette** | Color swatches from images | Hex values per color |
| **Quote** | Highlighted passages | Source context |
## Search and organization
### Smart search
Search titles, descriptions, tags, transcripts, and extracted text. Special tokens work automatically:
| Token | Examples | Effect |
| --- | --- | --- |
| **Color name** | `red`, `blue`, `teal` | Dominant palette color |
| **Visual style** | `minimal`, `dark`, `cinematic`, `pastel`, `vibrant` | Visual aesthetic |
| **Hex color** | `#FF5733`, `#3B82F6` | Exact color match |
| **Date** | `today`, `this week`, `january`, `last year` | Creation date |
| **Quick view** | `favorites` / `fav`, `trash` / `bin` / `deleted` | Favorites or trash |
| **Keyword** | anything else | Full-text match |
Mix tokens in one query — all recognized filters apply together.
```
blue button hover state
minimal dark
#3B82F6
feedback this week
```
### Tags and filters
AI applies tags automatically; you can add your own. Filter by type, favorites, style, color, or date. Active filters show as removable pills in the search bar.
### Trash
Deleted cards go to trash first. Restore them, or delete permanently (including files). Open trash with `trash`, `bin`, or `deleted` in the search bar.
### Import and export
From Settings on web and desktop:
:::note[Limits]
Imports accept up to 10,000 items per file. Exports can take a few minutes for
large libraries — keep the tab open until the archive downloads.
:::
- [Import](/docs/import) bookmarks, Raindrop CSV, or a Teak archive
- [Export](/docs/export) a portable ZIP of active cards and original files
### Grid
Cards show in a masonry grid that adapts to different sizes and aspect ratios.
## AI enrichment
Each card is processed automatically:
| Feature | Description |
| --- | --- |
| **Auto-tagging** | Keywords and concepts |
| **Summaries** | Short descriptions for scanning |
| **Categorization** | Link type (design, development, article, tool) |
| **Color extraction** | Dominant colors in images |
| **Transcription** | Audio → searchable text |
| **Thumbnails** | Previews for video and documents |
## Apps and access
Everything syncs in real time. Pick the surface that fits:
Native macOS app with automatic updates.
Share sheet, camera, and voice notes on iOS.
One-click save from Chrome, Safari, Edge, and more.
Programmatic access for tools and agents.
Sign in with your browser, or create a long-lived key under **Settings → API Keys**.
---
# Import Your Data
Source: https://teakvault.com/docs/import
Teak can import links and cards from a browser bookmarks export, a Raindrop.io CSV export, or a Teak data archive. Imports are available from Settings on the web app and desktop app.
:::note[Imports only add, never remove]
Importing does not delete or modify any of your existing cards. Links that match a card you already have are skipped, not duplicated.
:::
## Start an Import
1. **Open Settings**
Open Teak on web, or open the desktop app and choose **Teak -> Settings...** from the macOS menu bar.
2. **Open Import/Export**
In Settings, find **Import/Export Data** and choose **Manage**.
3. **Choose a mode**
Choose **Import Bookmarks**, **Import from Raindrop**, or **Import Teak Archive**.
4. **Choose your file**
Choose your file. Teak shows the file name and size for confirmation.
5. **Start import**
Choose **Start import** to begin. Progress updates live as Teak parses the file and creates cards.
You can cancel an import while it is uploading or in progress. If your browser closes or reloads mid-upload, reopen the dialog and choose **Resume upload** to continue from where it left off.
## Import Modes
| Mode | Source file | What comes in |
|---|---|---|
| **Import Bookmarks** | An HTML bookmarks export from any browser (`.html`, up to 20 MiB) | Each bookmark becomes a link card. Folder names become tags, and the original save date is preserved when present. |
| **Import from Raindrop** | A Raindrop.io CSV export (`.csv`, up to 20 MiB) | Each row becomes a link card with its title, notes, tags, folder (as a tag), favorite status, and saved date. |
| **Import Teak Archive** | A ZIP archive previously downloaded from [Export Your Data](/docs/export) (`.zip`, up to 5 GiB) | Cards are recreated with their original type, content, tags, notes, favorite status, palette colors, and attached files. Older archive document cards backed by `.md` or `.markdown` files become editable text cards with their raw Markdown and original source attachment. |
## Duplicate Handling
Before creating a card, Teak checks whether a non-deleted card with the same URL already exists in your library. Matching items are skipped and counted separately from created and failed items — they do not create a duplicate card.
Bookmark and Raindrop files can also contain duplicate links within the same file; only the first occurrence of a URL is imported, and later occurrences are skipped.
## Limits
| Limit | Details |
|---|---|
| File size | 20 MiB for bookmarks HTML and Raindrop CSV; 5 GiB for a Teak archive. |
| Cards per import | Up to 10,000 items in a single file. |
| File attachments | Each file inside a Teak archive must be 20 MiB or smaller to be attached to its card. |
| Markdown text | Imported `.md` and `.markdown` content must be valid UTF-8 and no larger than 512 KiB. |
| Concurrent imports | One import can run at a time. |
## After an Import Finishes
Teak shows how many items were created, skipped, and failed. If any items failed, you can copy or download a text report listing each one and the reason it could not be imported.
## Troubleshooting
Confirm the file matches the selected mode: bookmarks HTML, Raindrop CSV, or a Teak-exported ZIP. A wrong format or incompatible archive fails before cards are created.
Skipped items already exist in your library with the same URL. This is expected and does not indicate an error.
Open the import error report to see whether each item had an unsafe URL, exceeded a limit, or was missing from the archive.
Reopen **Import/Export Data** and choose **Resume upload** with the same file.
Reach out via [Support](/docs/support).
---
# MCP
Source: https://teakvault.com/docs/mcp
Teak provides a remote MCP server at `https://teakvault.com/mcp`.
## Base URLs
- Production: `https://teakvault.com/mcp`
- Local development: `http://localhost:3001/mcp`
- Discovery manifest: `https://teakvault.com/.well-known/mcp.json`
## Authentication
Teak's MCP server supports two authentication methods.
**Browser sign-in**
Spec-compliant MCP clients discover Teak's authorization server, open your browser to sign in, and store the resulting access token automatically. External clients show an approval screen with the requested access before Teak connects them. Access tokens are short-lived and refresh automatically.
For example, with Claude:
```bash
claude mcp add --transport http teak https://teakvault.com/mcp
```
Start the MCP connection, then complete the browser sign-in when prompted.
You can revoke a connection at any time from Teak Settings → **Security** → **Connections**. Disconnecting an app revokes its access across all installations, including its refresh credentials. Every subsequent MCP request checks access again, even in an already-open client. API-key connections are managed under **Security** → **API keys**.
Add Teak as a remote HTTP MCP server, complete browser sign-in, and list my
favorite cards.
## Transport
| Prop | Type | Default | Description |
| - | - | - | - |
| `Protocol` | `string` | - | MCP Streamable HTTP |
| `Endpoint path` | `string` | - | /mcp (also /mcp/) |
| `Server mode` | `string` | - | Stateless JSON response mode |
OAuth protected-resource discovery advertises the canonical production endpoint
shown above, so MCP clients validate and connect to the same public resource.
JSON-RPC batches are limited to 100 messages. Larger batches are rejected
before any tool runs. Single-call requests are unchanged.
## Available Tools
### Core card tools
- `teak_v1_list_cards`
- Input: `{ limit?: number, cursor?: string, type?: string, favorited?: boolean, tag?: string, sort?: "newest" | "oldest", createdAfter?: number, createdBefore?: number }`
- Output: `{ items: Card[], pageInfo: { hasMore: boolean, nextCursor: string | null } }`
- `teak_v1_get_card`
- Input: `{ cardId: string }`
- Output: full card object
- `teak_v1_create_card`
- Input: text/URL fields or uploaded-file fields `{ fileKey, fileEtag?, fileName, mimeType, fileSize?, cardType? }`. Pass the `ETag` response header from the upload PUT as `fileEtag` so Teak can verify the exact stored object. Explicit `cardType: "text"` stores raw Markdown exactly; automatic URL, quote, and palette detection remains when the type is omitted.
- Output: `{ status: "created", cardId: string, appUrl: string }`
- `teak_v1_list_tags`
- Input: `{}`
- Output: `{ items: { name: string, count: number }[] }`
- `teak_v1_get_card_changes`
- Input: `{ since: number, cursor?: string, limit?: number }`
- Output: `{ items: Card[], deletedIds: string[], pageInfo: { hasMore: boolean, nextCursor: string | null } }`
- `teak_v1_bulk_cards`
- Input: `{ operation: "create" | "update" | "favorite" | "delete", items: object[], confirm?: true }`
- Output: bulk operation results; delete batches require `confirm: true`
- `teak_v1_create_upload`
- Input: `{ fileName: string, mimeType: string, fileSize: number }`
- Output: `{ uploadUrl: string, fileKey: string, method: "PUT", maxFileSize: number, expiresIn: number }`
- Supports the same upload matrix as the web app, API, and CLI. `.md` and `.markdown` files become editable text cards and must be valid UTF-8 no larger than 512 KiB; other supported files allow up to 100 MB.
- `teak_v1_search_cards`
- Input: `{ q?: string, limit?: number }`
- Output: `{ items: Card[], total: number }`
- `teak_v1_list_favorite_cards`
- Input: `{ q?: string, limit?: number }`
- Output: `{ items: Card[], total: number }`
- `teak_v1_update_card`
- Input: `{ cardId: string, content?: string, url?: string, notes?: string | null, tags?: string[] }`
- Text-card content remains raw Markdown, preserved exactly, with a 512 KiB UTF-8 limit.
- Output: updated card object
- `teak_v1_set_card_favorite`
- Input: `{ cardId: string, isFavorited: boolean }`
- Output: updated card object
- `teak_v1_delete_card`
- Input: `{ cardId: string, confirm: true }`
- Output: `{ status: "deleted", cardId: string }`
### ChatGPT connector tools
Teak also exposes the plain `search` and `fetch` tools expected by ChatGPT connectors and Deep Research:
- `search` accepts `{ query: string }` and returns `{ results: [{ id, title, url }] }`.
- `fetch` accepts `{ id: string }` and returns `{ id, title, text, url, metadata }`.
## Error Format
Tool failures are returned as MCP tool errors with this structured shape:
```json
{
"status": 429,
"code": "RATE_LIMITED",
"error": "Too many requests"
}
```
## JSON-RPC Examples
```json
{
"jsonrpc": "2.0",
"id": 1,
"method": "initialize",
"params": {
"protocolVersion": "2025-06-18",
"capabilities": {},
"clientInfo": {
"name": "my-client",
"version": "1.0.0"
}
}
}
```
```json
{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/list",
"params": {}
}
```
```json
{
"jsonrpc": "2.0",
"id": 3,
"method": "tools/call",
"params": {
"name": "teak_v1_create_card",
"arguments": {
"content": "https://teakvault.com"
}
}
}
```
---
# Mobile App (iOS)
Source: https://teakvault.com/docs/mobile
The Teak mobile app lets you save inspiration on the go, capture voice notes, upload files, and browse your full library — all synced in real time with your other devices.
## Requirements
- iPhone running iOS 16.4 or newer
- A Teak account
## Install
Download the app from the [App Store](https://apps.apple.com/us/app/teak-save-inspirations/id6756574989) and sign in with your Teak account.
## Sign In
On first launch, Teak shows the welcome screen. Choose how you want to continue:
**Apple**
One-tap authentication using your Apple ID. Tap **Continue with Apple** and approve with Face ID or Touch ID. Fastest option on iOS.
**Google**
OAuth sign-in via a browser redirect. Tap **Continue with Google**, pick an account in the browser sheet, and you'll return to Teak when it completes.
**Email**
Tap **Login with Email** or **Register with Email** to open a native iOS form sheet. Both options take an email and password — tap the checkmark to confirm.
For new accounts, use a password of at least 8 characters. Teak will send a verification email you must open before signing in.
## Browsing Your Library
The **Home** tab shows your cards in a scrollable grid. Tap any card to open a full preview sheet with metadata, tags, notes, and action buttons.
## Saving Content
Open the **Add** tab to save new content manually:
| Action | What it does |
| ---------------- | ------------------------------------------------------- |
| **Text or URL** | Type or paste any text or link |
| **Record Audio** | Record a voice note; Teak auto-transcribes it |
| **Upload Files** | Pick images, documents, or other files from your device |
## Share Sheet (Import from Other Apps)
Use the iOS Share Sheet to save content to Teak without leaving another app:
1. In any app (Safari, Photos, Files, etc.), tap the **Share** button.
2. Select **Teak** from the share destinations.
3. The Teak share extension opens and saves the item automatically.
The share extension shows live status while saving:
- **Saving to your Teak vault…** — in progress
- **Your shared content was saved.** — success
- **Some items could not be saved.** — partial failure (individual items listed)
- **Shared content could not be saved.** — complete save failure
- **Sign in to save shared content.** — open Teak, sign in, then retry
- **Teak did not receive anything to share.** — share sheet was opened with no content
Supported share sources include links, text, images, and files. Files shared from Files or another app use the same source, Markdown, archive, Office, design, image, motion, and audio format support as Teak on the web, up to 100 MB.
## Settings
The **Settings** tab lets you:
- Switch appearance between **Auto** (follows iOS system setting), **Light**, and **Dark** via **Settings → Appearance**
- View your account email and card count
- Sign out
- Delete your account
## Troubleshooting
- Check your internet connection.
- Confirm your system clock is correct.
- Retry after a minute in case of a temporary authentication issue.
- Open the iOS Share Sheet from any app.
- Scroll the share destinations row and tap **More**.
- Enable **Teak** in the list.
- Open Teak and pull down to refresh.
- Check that you were signed in when you shared the item.
- If the status showed a partial failure, only some items may have saved.
Reach out via [Support](/docs/support).
---
# Privacy Policy
Source: https://teakvault.com/docs/privacy-policy
## Overview
Teak protects your privacy across the web app, desktop app, mobile app, browser extensions, Raycast extension, CLI, public API, and MCP server. We store and process the content you save securely.
## Data We Collect
- **Account data:** Authentication details, profile info (name, email, optional photo), and account preferences.
- **Your content:** Cards (notes, links, images, videos, audio, documents, palettes, quotes), metadata (timestamps, tags, favorites), and securely stored file uploads.
- **Usage data:** How you interact with our services, device/browser info for compatibility, and error logs for service improvement.
- **Extension and client data:** Page URL or text you explicitly choose to save, and similar capture data from share sheets, Raycast, CLI, API, or MCP when you use those surfaces.
## How We Use Your Data
- **Primary uses:** Store, organize, and sync your content; enable cross-platform access; process metadata and thumbnails; power search.
- **Secondary uses:** Improve service quality, provide technical support, maintain security, and meet legal requirements.
## Data Security
- Hosted storage in the United States with industry-standard encryption in transit and at rest
- Secure login sessions
- Isolation so your data stays private from other users
- Automated backups for durability
## Sharing & Disclosure
- We **never** share your personal content for advertising or third-party analytics; your cards and files remain private.
- Limited disclosure only for legal requirements (court orders), safety concerns, essential service providers, or business transfers (mergers/acquisitions).
## Your Rights & Controls
- Access: view all your content through our apps.
- Export: download your data from Settings (web and desktop).
- Delete: remove individual cards or your entire account.
- Control: manage privacy preferences and API keys.
**Deletion timeline:** soft delete provides a 30-day recovery period; permanent deletion happens after 30 days; full account deletion completes within 30 days of request.
## Platform Practices
- **Web and desktop:** essential cookies or local storage for authentication and performance; secure session management.
- **Mobile app:** device permissions only when used (camera, mic, photos); local caching for offline viewing.
- **Browser extension:** active tab access only when saving content; no background monitoring; activates on user interaction.
- **CLI, Raycast, API, MCP:** authenticate with browser sign-in or an API key you control; revoke keys anytime in Settings.
## International Data
Data may be processed outside your country, but primary storage remains in the US with strong privacy protections.
## Children's Privacy
Teak is not for users under 13; we don't knowingly collect data from children under 13.
## Changes to This Policy
Material updates are communicated via email or in-app notifications and reflected in the effective date.
## Contact
- Privacy questions: hi@praveenjuge.com (7-day response)
- Data requests: through account settings or direct contact (30-day processing)
## Legal Basis
- Contract performance (providing services)
- Legitimate interests (service improvement, security)
- Consent (optional features)
- Legal obligations
## Cookies
- **Essential:** authentication sessions, user preferences, security protection.
- **Analytics:** aggregate non-personal statistics, performance monitoring, no external tracking.
---
# Raycast Extension
Source: https://teakvault.com/docs/raycast
Use Teak in Raycast to save ideas and find cards without leaving your keyboard flow.
## Quick setup
1. Install the extension:
2. Run any Teak command and choose **Sign in with Browser**. Your browser opens to authorize Teak. Approve access on the consent screen, then Raycast finishes sign-in — no key to copy.
### Using an API key (optional)
Prefer an API key? Open the extension preferences and paste a key from Teak Settings → **Manage API Keys**. A configured API key takes precedence over browser sign-in, so existing setups keep working unchanged.
## Commands
- **Quick Save**: Open an input form to type or paste text and URLs to save.
- **Save to Teak**: Save any text or URL in one step. Accepts an optional argument and works as a [Raycast fallback command](https://manual.raycast.com/fallback-commands), so pressing Enter on a root search with no results can save that query straight to Teak.
- **Save Clipboard**: Save the current clipboard contents to Teak with no prompt.
- **Save Selected Text**: Save the text currently highlighted in any app. Ideal paired with a global hotkey.
- **Save Current Browser Tab**: Save the active browser tab directly from Raycast. Requires the [Raycast Browser Extension](https://www.raycast.com/browser-extension).
- **Search Cards**: Find and open cards instantly.
- **Favorites**: Jump to your starred cards.
- **Browse Tags**: See every tag in your vault with per-tag card counts, then drill into a tag to search within it.
Text saved from Raycast is stored as raw Markdown exactly as entered, while URL-only saves continue to become link cards.
## AI Tools
Teak exposes the following tools for [Raycast AI](https://www.raycast.com/ai):
| Tool | What it does |
| ------------------------- | ----------------------------------------------------------------- |
| **Save to Teak** | Save a note or URL to your Teak library. |
| **Search Teak Cards** | Search cards by text, type, tags, favorite state, and sort order. |
| **Get Recent Teak Cards** | Fetch the newest cards without a search query. |
| **Get Teak Card** | Fetch the full details of a specific card by ID. |
| **List Teak Tags** | List your tags with per-tag card counts. |
| **Toggle Favorite** | Favorite or unfavorite a card. Requires confirmation. |
AI tools use the same sign-in as the extension — no extra setup required.
## Security
- Browser sign-in connects Raycast to your Teak account without copying a key. Use **Sign Out** from any command's action panel to revoke this installation's access. If Teak cannot be reached, your credentials stay saved so you can retry. To disconnect every Raycast installation, use **Settings → Security → Connections**. API keys remain managed under **Security → API keys**.
- If you use an API key instead, it only connects Raycast to your Teak account. You can have up to 10 active keys. Revoke, regenerate, or revoke all keys from Teak Settings.
---
# Self-Hosting
Source: https://teakvault.com/docs/self-hosting
## What you'll need
- Convex CLI (`npm i -g convex`)
- Access to secrets for the features you want: Cloudflare Workers AI (AI), Kernel (screenshots), Resend (email), Polar (billing)
:::warning[Beta]
Self-hosting matches the hosted product, but you own uptime, secrets, and
billing integrations. Start with a local Convex deployment before pointing a
public domain at it.
:::
## Quickstart (local)
1. **Clone and run setup**
Clone the repo, then run the idempotent bootstrap:
```bash
bun run setup
```
Setup installs dependencies, provisions an isolated Convex development deployment, sets the local `SITE_URL` and `JWKS` defaults, pushes backend code, and derives `apps/web/.env.local` — no OAuth or billing credentials required. Verify with `bun run doctor`.
2. **Start a Convex dev deployment**
```bash
bunx convex dev
```
This keeps the dev deployment in sync and prints the `CONVEX_SITE_URL` and `CONVEX_URL`. It does not configure Better Auth — that's the next step.
3. **Configure essential secrets**
Run these commands to set the minimum required secrets in your Convex dashboard (`SITE_URL` is already set by setup):
```bash
# Security & Auth
npx convex env set BETTER_AUTH_SECRET $(openssl rand -base64 32)
npx convex env set TEAK_ADMIN_EMAIL you@example.com
# Optional: AI (if you want card processing)
npx convex env set CLOUDFLARE_ACCOUNT_ID your-account-id
npx convex env set CLOUDFLARE_API_TOKEN your-api-token
# Optional: Google sign-in (both or neither; email works without them)
npx convex env set GOOGLE_CLIENT_ID your-client-id
npx convex env set GOOGLE_CLIENT_SECRET your-client-secret
```
4. **Create local env files**
Copy the Convex URLs from your dashboard into each app's `.env.local`. Each app uses a framework-specific prefix for the same two vars:
| App | Prefix |
| -------------------------------- | -------------- |
| `apps/web` | `NEXT_PUBLIC_` |
| `apps/mobile` | `EXPO_PUBLIC_` |
| `apps/extension`, `apps/desktop` | `VITE_PUBLIC_` |
See [Detailed Environment Reference](#detailed-environment-reference) for the full variable list.
5. **Start the stack**
```bash
bun run dev
```
## Production basics
1. **Designate the administrator**
Set `TEAK_ADMIN_EMAIL` on the production Convex deployment to the normalized email address of the account that should receive administrative access. Teak fails closed when this value is absent or does not match a registered user; account creation order never grants administrative access.
2. **Update SITE_URL**
Update `SITE_URL` in Convex to your public domain (e.g., `https://app.yourdomain.com`).
3. **Point clients at production**
Update `CONVEX_SITE_URL` and `CONVEX_URL` in your client env files to point to your production deployment.
4. **Host the web app**
Point your domain's `SITE_URL` to wherever you are hosting the Next.js app.
5. **Add optional services**
Add email (`RESEND_API_KEY`) and billing (Polar) keys to Convex env if needed.
6. **Build and start**
```bash
bun run build
bun run start
```
## Detailed Environment Reference
Add these to your env files before running locally or deploying.
### Backend (`packages/convex/.env.local`)
```bash
SITE_URL=http://localhost:3000
JWKS=null # Static keys, or null for the live endpoint
PUBLIC_ORIGIN=https://yourdomain.com # Required to expose self-hosted /api and /mcp (else production URLs are advertised)
BETTER_AUTH_SECRET=your-secret # Better Auth security
TEAK_ADMIN_EMAIL=you@example.com # Explicit administrator account
FILES_BASE=https://files.yourdomain.com # Files Worker origin
FILES_SIGNING_SECRET=shared-secret # Same value as the worker's FILES_SIGNING_SECRET
R2_ACCESS_KEY_ID=access-key # R2 S3 access key (import archives + Markdown migration)
R2_SECRET_ACCESS_KEY=secret-key # R2 S3 secret key
R2_ENDPOINT=https://account.r2.cloudflarestorage.com
R2_BUCKET=teak-files # R2 bucket for private assets
KERNEL_API_KEY=token # Kernel Browser
CLOUDFLARE_ACCOUNT_ID=your-account-id # AI processing (Workers AI)
CLOUDFLARE_API_TOKEN=your-api-token # AI processing (Workers AI)
POLAR_ACCESS_TOKEN=token # Billing
POLAR_ORGANIZATION_TOKEN=token # Polar organization
POLAR_SERVER=sandbox # sandbox|production
POLAR_WEBHOOK_SECRET=secret # Polar webhooks
RESEND_API_KEY=token # Email service
```
### Files Worker (`apps/files-worker/.dev.vars`, wrangler secrets)
The Files Worker owns all file-byte operations (uploads, downloads,
renditions, AI analysis) and binds directly to your R2 bucket plus
Cloudflare Images and Workers AI:
```bash
FILES_SIGNING_SECRET=shared-secret # Must match the Convex value
```
The bucket binding is configured in `wrangler.jsonc` (`binding: "BUCKET"` —
set `bucket_name` to your own bucket). The worker config also declares
Cloudflare Images (`IMAGES`) and Workers AI (`AI`) bindings, so your account
needs both enabled.
Deploy it with `bunx wrangler deploy` from `apps/files-worker`. Its
`wrangler.jsonc` also declares Cloudflare Images and Workers AI bindings, so
your account needs both enabled. Point `FILES_BASE` in the backend env at the
worker's public origin.
### Web (`apps/web/.env.local`)
```bash
CONVEX_DEPLOY_KEY=
NEXT_PUBLIC_CONVEX_URL=https://deployment.convex.cloud
NEXT_PUBLIC_CONVEX_SITE_URL=https://deployment.convex.site
NEXT_PUBLIC_FILES_BASE=https://files.yourdomain.com # Mirror of FILES_BASE for the CSP
TEAK_DEV_APP_URL=http://localhost:3000 # Optional local override
```
The web Content-Security-Policy always allows the canonical file origins
(`https://files.teakvault.com` and the R2 storage origin). If you serve files
from custom origins, mirror the backend `FILES_BASE` into
`NEXT_PUBLIC_FILES_BASE` at web build time.
### Client Apps (`apps/mobile`, `apps/extension`, `apps/desktop`)
Mobile, Extension, and Desktop share the same base variables (use `EXPO_PUBLIC_` prefix for mobile, `VITE_PUBLIC_` for extension and desktop):
```bash
VITE_PUBLIC_CONVEX_URL=https://deployment.convex.cloud
VITE_PUBLIC_CONVEX_SITE_URL=https://deployment.convex.site
TEAK_DEV_APP_URL=http://localhost:3000 # Optional local override
```
#### Desktop-only
The desktop app additionally reads `VITE_WEB_URL` to know where to send sign-in and account links. Mobile and the extension do not use this variable.
```bash
VITE_WEB_URL=https://app.yourdomain.com # Defaults to https://app.teakvault.com
```
### Public API and MCP
```bash
PUBLIC_ORIGIN=https://yourdomain.com # Required to expose self-hosted /api and /mcp (else production URLs are advertised)
TEAK_DEV_API_URL=https://deployment.convex.site # Optional local override
```
Convex serves the REST API at `/api/v1`, the MCP endpoint at `/mcp`, plus `/healthz`, `/openapi.json`, and OAuth protected-resource metadata. In production, Teak exposes these through apex path rewrites (e.g. `https://teakvault.com/api` and `https://teakvault.com/mcp`). For self-hosted setups, configure your reverse proxy or DNS to route `/api` and `/mcp` to the Convex deployment's `.convex.site` domain. `SITE_URL` is the Better Auth application origin and the OAuth issuer; there is no separate issuer override.
:::warning[Breaking configuration change]
`PUBLIC_API_URL` and `PUBLIC_MCP_URL` were replaced by `PUBLIC_ORIGIN`, and
`AUTH_ISSUER_URL` was removed without a replacement (the issuer is always
`SITE_URL`). If you set the API or MCP variables, delete them and set
`PUBLIC_ORIGIN` to your public origin instead (for example, replace
`PUBLIC_API_URL=https://yourdomain.com/api` with
`PUBLIC_ORIGIN=https://yourdomain.com`). If you set `AUTH_ISSUER_URL`, delete
it and make sure `SITE_URL` is correct. There is no compatibility period:
the old names are ignored.
:::
## Where to get the values
- **Convex URLs**: Run `bunx convex dev`. It prints both `CONVEX_URL` (for the client) and `CONVEX_SITE_URL` (for the site/auth endpoint). You can also find these in the Convex Dashboard under "Settings" -> "Deployment".
- **Better Auth**:
- `BETTER_AUTH_SECRET`: Generate a random string (e.g., via `openssl rand -base64 32`).
- `SITE_URL`: This is the URL where your Next.js app is running. Locally, it's `http://localhost:3000`.
- `TEAK_ADMIN_EMAIL`: The normalized email address of the one account allowed to use administrative functions. Configure this independently for development and production.
- **Optional Features**:
- `R2_*`: Create a private Cloudflare R2 bucket and an API token/S3 credentials with object read, write, and delete access.
- `FILES_BASE` + `FILES_SIGNING_SECRET`: Deploy the Files Worker (see its section above); card uploads, downloads, thumbnails, and AI analysis all flow through it.
- `CLOUDFLARE_ACCOUNT_ID` + `CLOUDFLARE_API_TOKEN`: Get from the [Cloudflare dashboard](https://dash.cloudflare.com/) — create an API token with Workers AI run permission for AI-powered card processing.
- `KERNEL_API_KEY`: Get from [Kernel](https://onkernel.com/) for automated link screenshots.
- `RESEND_API_KEY`: Get from [Resend](https://resend.com/) for email verification and password resets.
- `POLAR_*`: Get from [Polar](https://polar.sh/) if you want to use the built-in billing system.
---
# Agent Skill
Source: https://teakvault.com/docs/skills
The Teak Agent Skill teaches AI agents how to save, search, and manage Teak cards through the CLI, API, MCP server, and TypeScript SDK.
[skills.sh/praveenjuge/teak](https://skills.sh/praveenjuge/teak)
## Install
```bash
npx skills add praveenjuge/teak --skill teak
```
Works with skills-compatible agents such as Codex, Claude Code, Cursor, GitHub Copilot, and Windsurf.
## What it covers
- When to use CLI vs API vs MCP vs SDK
- Browser sign-in or API key auth
- Save text, links, files, tags, and notes
- Search, update, favorite, delete, and sync cards
- Keep API keys and private content out of logs and prompts
## Use
```text
Use the Teak skill to save this research link with the tags ai and reference.
```
Agents with implicit skill activation may pick it up when a task mentions Teak.
## Related
- [Teak for AI Agents](/docs/ai-agents)
- [CLI](/docs/cli)
- [API](/docs/api)
- [API Reference](/reference)
- [MCP](/docs/mcp)
---
# Support
Source: https://teakvault.com/docs/support
## Troubleshooting first
- **Web / desktop:** refresh or relaunch, confirm you are signed in, check network.
- **Browser extension:** update the browser, disable other extensions temporarily, clear cache for the site you are saving.
- **Mobile:** latest App Store version, restart the app, stable connection; for share sheet issues see [Mobile](/docs/mobile#troubleshooting).
- **CLI / Raycast / API / MCP:** confirm sign-in or that your API key is still active in Settings; see [CLI](/docs/cli), [Raycast](/docs/raycast), [API](/docs/api), [MCP](/docs/mcp).
## Contact
- Email: hi@praveenjuge.com (typical response 24–48 hours)
- Billing and account: Settings → Upgrade / Billing, or email the address above
## Bug reports
1. [GitHub Issues](https://github.com/praveenjuge/teak/issues)
2. Steps to reproduce
3. Expected vs actual behavior
4. App, browser, or OS version if relevant
## Feature requests
[GitHub Issues](https://github.com/praveenjuge/teak/issues) with the **enhancement** label.
## Community
- [X/Twitter](https://x.com/praveenjuge)
- [GitHub](https://github.com/praveenjuge/teak)
---
# Terms of Service
Source: https://teakvault.com/docs/terms-of-service
## 1. Overview & Acceptance
These Terms of Service ("Terms") govern your use of Teak's web app, desktop app, mobile app, browser extensions, Raycast extension, CLI, public API, and MCP server (collectively, the "Service"). By creating an account, installing our apps, or using the Service, you agree to these Terms and our Privacy Policy.
## 2. Service Description
Teak is a personal knowledge hub that helps you capture, organize, and search inspiration and references across devices and integrations.
## 3. User Accounts
- **Registration:** provide accurate information; keep credentials secure; must be at least 13 years old; one person may not maintain multiple accounts.
- **Responsibilities:** you are responsible for all activity under your account; notify us immediately of unauthorized access; we may suspend or terminate accounts for violations.
## 4. Acceptable Use
- **Permitted:** store and organize your personal content; use across supported apps and integrations; export your data through built-in export.
- **Prohibited:** store illegal, harmful, or offensive content; violate intellectual property rights; reverse engineer or hack our systems; use for commercial redistribution without permission; spam, harass, or abuse other users; upload malware or malicious code; abuse the API, MCP, or free-tier limits.
## 5. Content & Intellectual Property
- **Your content:** you retain ownership; you grant us licenses to store, process, display your content and to create thumbnails and metadata; you represent you have rights to all content you upload.
- **Our content:** Teak's platform, design, and technology remain our property; you may not copy, modify, or redistribute proprietary code; open-source components follow their own licenses.
## 6. Privacy
Your privacy is important to us. Review the Privacy Policy to understand how we collect, use, and protect your information.
## 7. Subscription & Billing
- **Free tier:** basic features with reasonable usage limits; no credit card required; available for personal use.
- **Paid plans:** premium features and higher usage limits; billed through our subscription provider; auto-renews unless cancelled.
- **Refunds:** new Pro subscriptions include a 30-day full refund if you are not satisfied. After that window, charges are non-refundable for unused time or partial months unless required by law.
- **Payment terms:** provide current, complete payment information; you authorize charges to your payment method; update expired payment methods promptly; pricing changes may be given with 30 days' notice.
## 8. Service Availability
- **Uptime:** we strive for high availability but cannot guarantee 100% uptime; scheduled maintenance may cause temporary interruptions; we are not liable for service interruptions.
- **Changes to service:** we may add, modify, or remove features; we may discontinue the Service with reasonable notice; major changes will be communicated to users.
## 9. Limitation of Liability
- **Disclaimer:** Teak is provided "as is" without warranties of any kind, express or implied.
- **Liability cap:** total liability is limited to the amount you paid in the last 12 months; we are not liable for indirect, incidental, or consequential damages; we are not liable for lost data or business interruption.
- **Exclusions:** some jurisdictions do not allow exclusion of certain warranties, so these exclusions may not apply to you.
## 10. Termination
- **By you:** you may delete your account at any time; data is removed according to our deletion policy; refunds follow the policy in Section 7.
- **By us:** we may suspend access for violations; we may terminate accounts for repeated violations; we may terminate accounts inactive for 2+ years.
## 11. Governing Law
These Terms are governed by the laws of the United States and the state where our business is located, without regard to conflict of law principles.
## 12. Dispute Resolution
- **Informal resolution:** contact us first; we respond within 7 business days.
- **Formal resolution:** if informal steps fail, disputes go to binding arbitration under the rules of the American Arbitration Association.
- **Class action waiver:** disputes are resolved individually; class actions are waived.
## 13. Changes to Terms
We may update these Terms occasionally. We'll notify users of material changes via email or in-app notifications. Continued use of the Service after changes constitutes acceptance.
## 14. Contact
- General questions: hi@praveenjuge.com
- Legal issues: hi@praveenjuge.com
- Typical response: 7 business days
## 15. Severability
If any provision is unenforceable, the remaining provisions stay in full force and effect.
## 16. Entire Agreement
These Terms and the Privacy Policy are the entire agreement between you and Teak regarding the Service.
---
**Last Updated:** July 9, 2026
**Effective Date:** November 9, 2025
---
# Teak API
Source: https://teakvault.com/reference
Public API for creating, querying, and syncing Teak cards.
## Operations
---
# Execute bulk card operations
Source: https://teakvault.com/reference/operations/bulkcards
---
# Create a card
Source: https://teakvault.com/reference/operations/createcard
---
# Create a presigned upload
Source: https://teakvault.com/reference/operations/createupload
---
# Delete a card
Source: https://teakvault.com/reference/operations/deletecard
---
# Find a non-deleted card by exact URL
Source: https://teakvault.com/reference/operations/findduplicatecard
---
# List v1 endpoints
Source: https://teakvault.com/reference/operations/getapidiscovery
---
# Get a card
Source: https://teakvault.com/reference/operations/getcard
---
# Health check
Source: https://teakvault.com/reference/operations/gethealth
---
# List card changes since a timestamp
Source: https://teakvault.com/reference/operations/listcardchanges
---
# List cards
Source: https://teakvault.com/reference/operations/listcards
---
# List tags
Source: https://teakvault.com/reference/operations/listtags
---
# Set favorite state
Source: https://teakvault.com/reference/operations/setcardfavorite
---
# Update a card
Source: https://teakvault.com/reference/operations/updatecard