# Quick Start

This guide walks you through the basic workflow: setting your API key, creating a client, fetching a prompt, and using it with the Vercel AI SDK. By the end, your prompts will be managed in the [Promptly CMS](https://promptlycms.com) - not hardcoded in your codebase.

1. **Set your API key**

   Add your Promptly API key to your environment. Create a `.env` file in your project root:

   ```bash title=".env"
   PROMPTLY_API_KEY=pk_live_...
   ```

**Note:** Get your API key from the [Promptly CMS dashboard](https://app.promptlycms.com/settings?apiKeys). The SDK reads `PROMPTLY_API_KEY` from the environment automatically if no `apiKey` is passed to the client.

2. **Create a client**

   ```typescript title="src/index.ts"
   import { createPromptlyClient } from '@promptlycms/prompts';

   const promptly = createPromptlyClient();
   ```

   You can omit `apiKey` if `PROMPTLY_API_KEY` is set in your environment - the SDK picks it up automatically.

3. **Fetch a prompt**

**Caution:** Prompts must be **published** before the SDK can fetch them - drafts are not accessible via the API. In the CMS editor, click **Publish** in the top-right corner to make your prompt available.

   ```typescript title="src/index.ts"
   const result = await promptly.getPrompt('JPxlUpstuhXB5OwOtKPpj');

   // Prompt content - exactly what you wrote in the editor
   result.systemMessage; // 'You are a helpful assistant.'
   result.promptName;    // 'Code Review Helper'

   // Model config - from the sidebar settings in the editor
   result.model;         // LanguageModel (auto-resolved)
   result.temperature;   // 0.7

   // Template variables - interpolate ${variables} from your user message
   const message = result.userMessage({
     name: 'Alice',
     task: 'code review',
   });
   ```

**Finding your prompt ID:** You can find the prompt ID in two ways:
     - **From the URL** - it's the last segment: <code>https://app.promptlycms.com/prompts/<strong style="background: hsla(215, 60%, 50%, 0.25); border-radius: 4px; text-decoration: underline;">JPxlUpstuhXB5OwOtKPpj</strong></code>
     - **From the menu** - click **File → Copy Prompt ID** in the editor

4. **Use with the [Vercel AI SDK](https://ai-sdk.dev/)**

   Destructure `getPrompt()` and pass the properties directly to `generateText()` or `streamText()`:

   ```typescript title="src/index.ts"
   import { generateText } from 'ai';

   const { userMessage, systemMessage, temperature, model } = await promptly.getPrompt('JPxlUpstuhXB5OwOtKPpj');

   const { text } = await generateText({
     model,
     system: systemMessage,
     prompt: userMessage({ name: 'Alice', task: 'code review' }),
     temperature,
   });
   ```

## Complete example

```typescript title="src/index.ts"
import { createPromptlyClient } from '@promptlycms/prompts';
import { generateText } from 'ai';

const { getPrompt } = createPromptlyClient();

const { userMessage, systemMessage, temperature, model } = await getPrompt(
  'JPxlUpstuhXB5OwOtKPpj',
);

const { text } = await generateText({
  model,
  system: systemMessage,
  prompt: userMessage({ name: 'Alice', task: 'code review' }),
  temperature,
});

console.log(text);
```

## Composers

Composers let you orchestrate multiple prompts into a single output. Fetch a composer with `getComposer()`, run each prompt through an AI model, and stitch the results together with `formatComposer()`:

```typescript title="src/composer-example.ts"
import { createPromptlyClient } from '@promptlycms/prompts';
import { generateText } from 'ai';

const promptly = createPromptlyClient();

const composer = await promptly.getComposer('my-composer', {
  input: { text: 'Hello', targetLang: 'French' },
});

const { introPrompt, reviewPrompt, formatComposer } = composer;

const output = formatComposer({
  introPrompt: await generateText(introPrompt),
  reviewPrompt: await generateText(reviewPrompt),
});
```

Each named prompt on the composer result (like `introPrompt` and `reviewPrompt`) is a `ComposerPrompt` object with `model`, `system`, `prompt`, and `temperature` properties -- ready to spread directly into `generateText()` or `streamText()`. The `formatComposer()` function reassembles the final output from each prompt's result, interleaving static content segments in the correct order.

## Next steps

- [Generate types](https://docs.promptlycms.com/getting-started/type-generation/) for autocomplete and type safety
- Learn about [fetching prompts](https://docs.promptlycms.com/guides/fetching-prompts/) in detail
- Explore the [AI SDK integration](https://docs.promptlycms.com/guides/ai-sdk-integration/) guide
- See the [Client API reference](https://docs.promptlycms.com/reference/client-api/) for `getComposer()` and `getComposers()` details
- Manage your prompts, models, and versions from the [Promptly CMS dashboard](https://promptlycms.com)
- Need direct API access? See the [REST API reference](https://docs.promptlycms.com/api/overview/)