# Quickstart

From sign-up to a working prompt call in five minutes.

This walkthrough gets you from zero to a typed prompt call in your code. We'll create a workspace, publish a tiny prompt, install the CLI, generate code, and call the prompt.

## 1. Sign up and create a workspace

Head to [sufleur.com](https://sufleur.com), register an account, and create a workspace. Your workspace name becomes the prefix for every prompt you publish: a workspace called `acme` produces prompts like `@acme/welcome-message`.

## 2. Generate an API key

Open your workspace settings and create an API key. Keep it somewhere safe — you'll feed it to the CLI through an environment variable in the next step.

## 3. Author and publish a prompt

In the web app, create a new prompt called `welcome-message`. Add a single entrypoint file (for example `userPrompt`) with this template:

```mustache
Hi {{user.name}}{{@type string}}{{@doc User's first name}}, welcome aboard!
```

Save the draft, then publish version `0.1.0`.

> [!NOTE] What just happened
>
> You created a prompt, started a draft version of it, added a template file as an entrypoint,
> and then published the draft as `0.1.0`. From now on, that exact template is what your code
> will resolve. The [Concepts page](/docs/concepts) walks through prompts, versions, and files
> in more detail.

## 4. Install the CLI

Pick the wrapper that matches your project. Both ship the same Go binary.

#### TypeScript

```bash
pnpm add -D @sufleur/cli
# or: npm i -D @sufleur/cli
# or: yarn add -D @sufleur/cli
```

#### Python

```bash
uv add --dev sufleur-cli
# or: pip install sufleur-cli
```

## 5. Initialize your project

From the root of your project, run:

```bash
sufleur init
```

You'll be prompted for your workspace name, the env var that holds your API key, the output language, and where to write the generated file. The result is a `sufleur.yaml` like this:

```yaml
api_keys:
  acme: ${ACME_API_KEY}

prompts: {}

output:
  language: typescript
  file: ./generated/prompts.ts
```

Set `ACME_API_KEY` in your environment or in a local `.env` file (the CLI loads `.env` automatically).

## 6. Add the prompt and generate code

```bash
sufleur add @acme/welcome-message
sufleur generate
```

`add` validates the prompt exists, writes it to `sufleur.yaml`, resolves the latest matching version, and caches it under `.sufleur/`. `generate` reads the lockfile and writes typed code to the path in `output.file`.

> [!TIP] Two-step or one-step
>
> `sufleur add` already runs install for you. If you only changed `sufleur.yaml` by hand, run
> `sufleur install` separately to refresh the lockfile, then `sufleur generate`.

## 7. Call the prompt from your code

#### TypeScript

```ts
import { getPrompt } from './generated/prompts'

const welcome = getPrompt('@acme/welcome-message')

const { prompt } = welcome.render('userPrompt', {
  user: { name: 'Ada' },
})

// `prompt` is the rendered string — pass it to your LLM client of choice.
console.log(prompt)
```

#### Python

```python
from generated.prompts import get_prompt

welcome = get_prompt('@acme/welcome-message')

result = welcome.render('userPrompt', {
    'user': {'name': 'Ada'},
})

# `result['prompt']` is the rendered string.
print(result['prompt'])
```

The `user.name` argument is required and typed — your editor knows the shape because the CLI inferred it from the Mustache template plus the `{{@type string}}` annotation.

## What's next

- Add an [output schema](/docs/mustache#outputschema) so `parseOutput()` returns a validated object.
- Read the [CLI reference](/docs/cli) for `update`, `--frozen` (CI mode), and aliases.
- Open the [SDK page](/docs/sdk/node) for your language to see the full surface of the generated code.