Raycast Extension

The Figa Raycast extension gives paid workspace users quick desktop access to workspace context, expenses, monthly totals, categories, recipients, expense creation, and selected-expense payment actions.

Paid workspace required

API keys are available for Pro and Enterprise workspaces. Figa checks the plan at request time, so a key created while the workspace was paid stops working if the workspace is downgraded to Free.

Setup

1
Open Figa workspace settings and create a dedicated API key for Raycast.
2
Choose the read preset for lookup-only commands or the write preset for create and payment workflows.
3
Copy the key immediately. Figa shows the raw API key only once.
4
Install or run the Figa Raycast extension and open extension preferences.
5
Paste the key into API Key.
6
Run Show Workspace Context first to verify workspace, plan, defaults, and capabilities.

Raycast extension preferences

Capture the API Key preference with the key redacted.

Suggested file: /help/screenshots/integrations/raycast/preferences-redacted.png

Placeholder. Replace with real screenshot once flow is finalized.

API key safety

API keys are shown once. Create a key dedicated to Raycast, store it only in Raycast preferences, and rotate it from Figa workspace settings if it was pasted into logs, screenshots, chat, or another tool.

Preferences

Preference	Value	Notes
`API Key`	Password field	Use a workspace API key. Raycast stores it as an extension password preference.

Capabilities

Every command starts from GET /api/v1/context. Context v2 includes workspace defaults and capability flags derived from the configured key. Raycast uses those flags to show clear permission states before mutation requests are sent.

defaults.baseCurrency pre-fills create-expense currency.
expenses.read gates expense search and monthly totals.
categories.read and recipients.read gate reference commands and create-form choices.
expenses.write gates expense creation.
expenses.payments gates selected-expense mark-paid actions. Legacy write keys may still be accepted by the API payment route.

Commands

Command	Capability	Expected behavior
Show Workspace Context	`workspaces.read`	Shows workspace, plan, critical limits, defaults, capabilities, and key settings links.
Search Expenses	`expenses.read`	Shows current-month expenses with all, unpaid, and paid views plus copy, paste, and Figa links.
Show Monthly Summary	`expenses.read`	Shows recent total, paid, and unpaid monthly values using workspace currency.
Search Categories / Search Recipients	`categories.read`, `recipients.read`	Shows live workspace/global reference data with expense counts and Figa links.
Create Expense	`expenses.write`	Uses workspace defaults and live references, validates form fields, and sends an idempotent create request.
Mark Expense Paid	`expenses.payments`	Reads remaining amount, asks for confirmation, records an idempotent payment, and refreshes the list.

Manual QA Matrix

State	Expected result
Free workspace key	Commands show paid-plan-required state and link to billing or API key settings.
Pro valid key	Context and allowed commands load normally; plan tier reads `pro`.
Enterprise valid key	Context and allowed commands load normally; plan tier reads `enterprise`.
Read-only key	Read commands work; create and payment workflows show permission details without sending mutations.
Write key	Read commands, create expense, and mark-paid payment action work when capabilities are present.
Invalid or expired key	Commands show invalid-key state and actions to update extension preferences.
Missing permission	Command-specific detail names the missing capability and links to API key settings.
Rate limit	Commands show rate-limited state and keep retry available.

Workflow QA

Expense search (#530): verify all, unpaid, and paid filters; formatted amounts; dates; copy/paste actions; Figa deep links; empty state.
Monthly summary (#530): verify seven-month total, paid, and unpaid values match the workspace.
Reference commands (#542): verify category and recipient search, global/workspace scope labels, expense counts, and links.
Create expense (#543): verify read-only gate, write-key success, invalid amount/name/currency validation, category/recipient live choices, base-currency default, and duplicate-submit behavior.
Payment action (#531): verify read-only gate, confirmation dialog, remaining-amount payment, success toast, refreshed list, already-paid action absence, and retry after unknown failure.

Create Expense command

Capture a redacted form with workspace categories and recipients visible.

Suggested file: /help/screenshots/integrations/raycast/create-expense-form.png

Placeholder. Replace with real screenshot once flow is finalized.

Expense list with mark-paid action

Capture an unpaid selected expense with action panel open and no sensitive workspace data.

Suggested file: /help/screenshots/integrations/raycast/expense-mark-paid-action.png

Placeholder. Replace with real screenshot once flow is finalized.

Local Development

1
From the monorepo root, run pnpm -F figa dev for local Raycast development.
2
Use pnpm -F figa build before release checks. Raycast Store review builds the standalone package with npm.
3
Use pnpm -F figa lint for ESLint and Prettier, then npm run lint:store from apps/raycast when Store metadata is ready.
4
Do not capture raw API keys or customer workspace names in screenshots.

pnpm -F figa dev
pnpm -F figa build
pnpm -F figa lint

cd apps/raycast
npm run lint:store

Release Checklist

Confirm apps/raycast/package.json version, title, description, categories, commands, and author metadata.
Run pnpm -F figa build, pnpm -F figa lint, and npm run lint:store from apps/raycast.
Verify package-lock.json is committed because Raycast Store review uses npm.
Review command names, subtitles, empty states, permission details, and error states for customer-safe wording.
Capture Store screenshots with redacted data: context, expense list, create form, reference search, and permission/error state.
Confirm screenshots do not show raw API keys, real customer data, local API URLs, or staging domains.
Prepare Raycast Store submission notes covering paid-plan requirement, API key setup, and supported commands.
Keep OAuth/pairing and Raycast AI tools as roadmap notes until backend support and #533 decisions exist.

Roadmap

OAuth, pairing flow, private team distribution, and Raycast AI tools are not part of the first release. Use this API-key setup until those flows are designed and documented. The Raycast AI spike recommends deferring AI tools until the regular extension has shipped.