> For the complete documentation index, see [llms.txt](https://developers.raycast.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.raycast.com/api-reference/preferences.md).

# Preferences

Use the Preferences API to make your extension configurable.

Preferences are configured in the [manifest](/information/manifest.md#preference-properties) per command or shared in the context of an extension.

Required preferences need to be set by the user before a command opens. They are a great way to make sure that the user of your extension has everything set up properly.

## Help for Required Preferences

Add an optional `help.md` file to the root of your extension, next to `package.json`, to explain how to fill in required preferences. Raycast renders its Markdown beside the setup form when a command or tool needs required preferences that haven't been set. The same help file is used throughout the extension, so include any instructions needed for both shared and command-specific preferences.

For example, a `help.md` file for an extension that requires an API key could contain:

```markdown
# Set Up Your API Key

1. Sign in to your account on the service's website.
2. Open **Settings → API Keys** and create a key with read access.
3. Copy the key into the **API Key** preference, then continue.

Only read access is needed to search your account's data.
```

The filename is case-insensitive when building; `help.md`, `Help.md`, and `HELP.md` are all supported.

Keep this file focused on setup steps, such as obtaining credentials or enabling a setting in another application. Use `README.md` for the extension's general documentation. When help content is available, the setup form displays it in place of the **About this Extension** link to the README.

## API Reference

### getPreferenceValues

A function to access the preference values that have been passed to the command.

Each preference name is mapped to its value, and the defined default values are used as fallback values.

#### Signature

```typescript
function getPreferenceValues(): { [preferenceName: string]: any };
```

{% hint style="info" %}
You don't need to manually set preference types as an interface since it is autogenerated in `raycast-env.d.ts` when you run the extension.
{% endhint %}

#### Example

```typescript
import { getPreferenceValues } from "@raycast/api";

export default async function Command() {
  const preferences = getPreferenceValues<Preferences>();
  console.log(preferences);
}
```

#### Return

An object with the preference names as property key and the typed value as property value.

Depending on the type of the preference, the type of its value will be different.

| Preference type | Value type                                               |
| --------------- | -------------------------------------------------------- |
| `textfield`     | `string`                                                 |
| `password`      | `string`                                                 |
| `checkbox`      | `boolean`                                                |
| `dropdown`      | `string`                                                 |
| `appPicker`     | [`Application`](/api-reference/utilities.md#application) |
| `file`          | `string`                                                 |
| `directory`     | `string`                                                 |

### openExtensionPreferences

Opens the extension's preferences screen.

#### Signature

```typescript
export declare function openExtensionPreferences(): Promise<void>;
```

#### Example

```typescript
import { ActionPanel, Action, Detail, openExtensionPreferences } from "@raycast/api";

export default function Command() {
  const markdown = "API key incorrect. Please update it in extension preferences and try again.";

  return (
    <Detail
      markdown={markdown}
      actions={
        <ActionPanel>
          <Action title="Open Extension Preferences" onAction={openExtensionPreferences} />
        </ActionPanel>
      }
    />
  );
}
```

#### Return

A Promise that resolves when the extensions preferences screen is opened.

### openCommandPreferences

Opens the command's preferences screen.

#### Signature

```typescript
export declare function openCommandPreferences(): Promise<void>;
```

#### Example

```typescript
import { ActionPanel, Action, Detail, openCommandPreferences } from "@raycast/api";

export default function Command() {
  const markdown = "API key incorrect. Please update it in command preferences and try again.";

  return (
    <Detail
      markdown={markdown}
      actions={
        <ActionPanel>
          <Action title="Open Command Preferences" onAction={openCommandPreferences} />
        </ActionPanel>
      }
    />
  );
}
```

#### Return

A Promise that resolves when the command's preferences screen is opened.

## Types

### Preferences

A command receives the values of its preferences via the [`getPreferenceValues`](#getpreferencevalues) function. It is an object with the preferences' `name` as keys and their values as the property's values.

Depending on the type of the preference, the type of its value will be different.

| Preference type | Value type                                               |
| --------------- | -------------------------------------------------------- |
| `textfield`     | `string`                                                 |
| `password`      | `string`                                                 |
| `checkbox`      | `boolean`                                                |
| `dropdown`      | `string`                                                 |
| `appPicker`     | [`Application`](/api-reference/utilities.md#application) |
| `file`          | `string`                                                 |
| `directory`     | `string`                                                 |

{% hint style="info" %}
Raycast provides a global TypeScript namespace called `Preferences` which contains the types of the preferences of all the commands of the extension.

For example, if a command named `show-todos` has some preferences, its `getPreferenceValues`'s return type can be specified with `getPreferenceValues<Preferences.ShowTodos>()`. This will make sure that the types used in the command stay in sync with the manifest.
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.raycast.com/api-reference/preferences.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.