---
url: /guides/use-raycast.md
description: >-
  Add, find and update Hule tasks from Raycast on your Mac, without opening the
  app.
---

# Use Hule from Raycast

Use the Hule extension for [Raycast](https://www.raycast.com) when you want to add or find a task
from anywhere on your Mac without switching to Hule. From Raycast you can:

* add tasks;
* search your [workspaces](/concepts/hule-model);
* list what is [assigned](/guides/assign-and-watch-tasks) to you;
* [change a task](#change-a-task-from-raycast) without opening it in Hule.

## Before you start

You need a Mac with Raycast and a personal API token from Hule, which you create below.

::: warning macOS only
The extension runs only on macOS. Install [Raycast](https://www.raycast.com) first.
:::

## Get a token for Raycast

::: info The token, not your password
The extension signs in with a **personal API token**, and reaches exactly what your account can
reach (see [Permissions and access](/reference/permissions-and-access)).
:::

1. In Hule, click your name at the bottom of the sidebar and choose
   [**User settings**](/guides/manage-your-account).
   The settings open on **Account**.
2. Open **API tokens**.
   The **New token** form is at the top of the page.
3. In **Name**, type something you will recognise, for example **Raycast on my Mac**.
4. Under **Expires**, keep **Never** or choose when the token stops working:
   * **In 30 days**;
   * **In 90 days**;
   * **In a year**;
   * **Custom…**, a number of days you type.
5. Click **Create token**.
   The token appears, starting with `hule_pat_`.
6. Click **Copy**.
   The token is on your clipboard, ready for Raycast.
7. Click **Done — it is saved**.

   ::: warning The token is shown once
   After **Done — it is saved** you can't see the token again. If you lose it, create a new one.
   :::

## Install the extension

1. Open Raycast and search the **Store** for **Hule**.
   The Hule extension appears in the results.

2. Press Enter on **Hule** to install it.
   The Hule commands appear in Raycast's search.

3. Run any Hule command, for example **My Tasks**.
   Raycast asks for the extension's preferences.

4. Paste the token into **Personal API Token**. Leave **API URL** as it is.

   ::: warning "Hule rejected the token"?
   The token was pasted incomplete, has expired or was revoked. Copy it again from Hule, or
   [create a new one](#get-a-token-for-raycast), and paste it into **Personal API Token**.
   :::

5. Optional: set **Default List**, the [list](/concepts/hule-model) quick-added tasks go to,
   written as `List` or `Workspace / List`, for example:

   ```text
   Acme / Inbox
   ```

   The command you started opens.

   ::: info Default List wins over your Inbox list
   Quick Add picks the list in this order: **Default List**, then your
   [Inbox list](/guides/capture-to-inbox#inbox-list-setting) from Hule's GTD settings, then the
   first list you can add to.
   :::

## Add a task in one line

1. In Raycast, type **Quick Add Task** and press Tab.
   A title field appears next to the command.
2. Type the title and press Enter.
   The message "Added to …" names the list, with **Open in Hule** to jump there.

   ::: warning "Default List not found" or "is ambiguous"?
   No list you can edit has that name, or several do. Fix **Default List** in the extension's
   preferences (**Open Extension Preferences**): check the spelling, or write it as
   `Workspace / List`.
   :::

   ::: warning "Several Inbox lists"?
   **Default List** is empty and your Inbox list is set in more than one workspace. Set
   **Default List** to the one Quick Add should use (**Open Extension Preferences**).
   :::

A quick-added task has no assignee, so it doesn't show in **My Tasks** until you assign it; find
it in **Search Tasks**, where recently updated tasks come first.

**Quick Add Task** takes the title as is: it doesn't read dates from the text. For a date, use
[Create Task](#add-a-task-with-a-date-or-an-assignee).

## Add a task with a date or an assignee

1. In Raycast, run **Create Task**.
   A form opens.
2. Fill in **List** and **Title**. Set any of **Description**, **Priority**, **Due Date** and
   **Assignee**, then press Cmd+Enter.

## Find a task

* **Search Tasks** searches all your workspaces. With an empty search it shows recently updated
  tasks.
* **My Tasks** lists open tasks assigned to you, in groups:
  * **Overdue**;
  * **Today**;
  * **Tomorrow**;
  * **Later**;
  * **No Due Date**.

If you belong to several workspaces, **Search Tasks** can search just one: pick it from the menu
next to the search bar. The menu starts at **All Workspaces** and then remembers your last choice.

Press Enter on a task to see its details in Raycast.

## Change a task from Raycast

::: warning Edit access needed
In a list where you have [**Read** access](/concepts/sharing), Raycast doesn't offer the change
actions or **Delete Task**.
:::

1. In **Search Tasks** or **My Tasks**, select the task and press Cmd+K.
   The list of actions opens.
2. Choose an action and pick the new value.
   The task updates in Hule at once.

| Action | Shortcut | What it does |
|---|---|---|
| **Change Status…** | Option+S | Moves the task to another [status](/concepts/statuses) of its list. |
| **Change Priority…** | Option+P | Sets the priority. |
| **Set Due Date…** | Option+D | Sets the due date. |
| **Assign to…** | Option+A | Picks the [assignee](/guides/assign-and-watch-tasks), or **Nobody**. |
| **Open in Hule** | — | Opens the task in the [desktop app](/guides/install-the-desktop-app) if it is installed, otherwise in the browser. |
| **Copy Link** | Cmd+Shift+C | Copies the task's address. |
| **Delete Task** | Ctrl+X | Deletes the task after you click **Delete** in **Delete this task?**. |

::: danger Delete Task can't be undone
The task is deleted for good, with its [subtasks](/guides/break-down-with-subtasks) and
[comments](/guides/comment-and-mention).
:::

## Capture a task during a call

On a call, Kate opens Raycast, types **Quick Add Task**, presses Tab, then types
**Send the contract to Boris**. She presses Enter, and Raycast shows "Added to Inbox". After the call she opens
**Search Tasks**, where the new task is at the top of the recent tasks, presses
Option+D and picks tomorrow.

## Revoke access

1. In Hule, open **User settings** → **API tokens**.
2. Click **Revoke** next to the token, then **Revoke** again to confirm.
   The extension stops working at once.

::: danger Revoking can't be undone
A revoked token never works again. To reconnect Raycast, [create a new
token](#get-a-token-for-raycast) and paste it into **Personal API Token**.
:::

## If it doesn't work

* **"Default List not found".** No list you can edit has that name. Check the spelling in
  [**Default List**](#install-the-extension), or pick a list where you have
  [Edit access](/guides/share-a-folder-or-list).
* **"Default List is ambiguous".** Several lists have that name. Write
  [**Default List**](#install-the-extension) as `Workspace / List`
  (**Open Extension Preferences**); if both are in the same workspace,
  [rename one](/guides/organize-folders-and-lists#rename-and-change-icons) in Hule.
* **"Several Inbox lists".** **Default List** is empty, and you set an
  [Inbox list](/guides/capture-to-inbox#inbox-list-setting) in several workspaces. Set
  [**Default List**](#install-the-extension) to one of them.
* **"No list to write to".** You have no list you can add tasks to. Ask for
  [Edit access](/guides/share-a-folder-or-list) to a list, or
  [create one](/guides/organize-folders-and-lists#create-a-list) in Hule.
* **"Cannot Reach Hule" or "Could not create the task" — "Hule rejected the token".** The token
  has expired or was revoked. [Create a new one](#get-a-token-for-raycast) and paste it into
  **Personal API Token**: use **Open Extension Preferences** on the **Cannot Reach Hule** screen,
  or open the extension's preferences in Raycast's settings.

## Related

* [Capture tasks to your Inbox list](/guides/capture-to-inbox) — Raycast as one way to capture.
* [Find anything](/guides/find-anything) — search and pins inside Hule.
* [Install the desktop app](/guides/install-the-desktop-app) — where **Open in Hule** opens tasks.
* [Connect an AI agent](/guides/connect-an-ai-agent) — another tool that works on your tasks.
* [Permissions and access](/reference/permissions-and-access) — what your account can reach, and
  so what Raycast can.
* [Manage your account](/guides/manage-your-account) — your other user settings.