# CLI

## `promptly generate`

Fetches all prompts and composers from the Promptly API and generates a `promptly-env.d.ts` TypeScript declaration file. The CLI automatically places the file in your `src/types/` or `types/` directory if one exists, otherwise it falls back to the project root. Use `--output` to override.

```bash
bunx promptly generate
```
```bash
npx promptly generate
```
```bash
yarn dlx promptly generate
```
```bash
pnpm dlx promptly generate
```
## Flags

| Flag | Alias | Type | Default | Description |
|------|-------|------|---------|-------------|
| `--api-key` | | `string` | `process.env.PROMPTLY_API_KEY` | API key for authentication |
| `--output` | `-o` | `string` | Auto-detected (see below) | Output file path |

## Authentication

The CLI reads the API key in this order:

1. `--api-key` flag (highest priority)
2. `PROMPTLY_API_KEY` environment variable

```bash
# Using environment variable
PROMPTLY_API_KEY=pk_live_... npx promptly generate

# Using flag
npx promptly generate --api-key pk_live_...
```

## Output file

### Default location

The CLI automatically detects the best location for the generated file:

1. **`src/types/promptly-env.d.ts`** - if a `src/types/` directory exists
2. **`types/promptly-env.d.ts`** - if a `types/` directory exists
3. **`./promptly-env.d.ts`** - fallback (project root)

To override this, use the `--output` (`-o`) flag:

```bash
npx promptly generate --output ./custom/path/promptly-env.d.ts
```

### Generated file contents

The generated file is a TypeScript declaration file that augments the `@promptlycms/prompts` module. When composers are present, `ComposerVariableMap` and `ComposerPromptMap` are also generated:

```typescript title="promptly-env.d.ts"
// Auto-generated by @promptlycms/prompts - do not edit
import '@promptlycms/prompts';

declare module '@promptlycms/prompts' {
  interface PromptVariableMap {
    'prompt-id': {
      [V in 'latest' | '2.0.0' | '1.0.0']: {
        variableName: string;
      };
    };
  }
  interface ComposerVariableMap {
    'composer-id': {
      [V in 'latest' | '1.0.0']: {
        text: string;
        targetLang: string;
      };
    };
  }
  interface ComposerPromptMap {
    'composer-id': 'translatePrompt' | 'reviewPrompt';
  }
}
```

### Version grouping

The codegen groups versions with identical template variables together using mapped types:

```typescript
// Versions 'latest', '2.0.0', and '1.0.0' all share the same variables
[V in 'latest' | '2.0.0' | '1.0.0']: {
  pickupLocation: string;
  items: string;
};
```

If different versions have different variables, they are expressed as intersection types:

```typescript
'my-prompt': {
  [V in 'latest' | '2.0.0']: {
    name: string;
    email: string;
  };
} & {
  [V in '1.0.0']: {
    name: string;  // v1 only had 'name'
  };
};
```

### Prompts with no variables

Prompts whose `userMessage` contains no `${variable}` patterns get `Record<string, never>`:

```typescript
'static-prompt': {
  [V in 'latest' | '1.0.0']: Record<string, never>;
};
```

## Missing provider warnings

The CLI checks whether required provider packages are installed and warns if any are missing. This includes models referenced by both prompts and composer prompt segments:

```
  Found 3 prompt(s)
  Found 1 composer(s)
  Warning: "Review Prompt" requires @ai-sdk/anthropic - install it: npm install @ai-sdk/anthropic
  Generated ./promptly-env.d.ts
```

**Tip:** These are warnings only - the declaration file is still generated. Install the missing packages before using the prompts at runtime.

## How it works

1. Reads `PROMPTLY_API_KEY` from the environment (or `--api-key` flag)
2. Calls `GET /prompts?include_versions=true` and `GET /composers?include_versions=true` in parallel
3. Extracts `${variable}` template patterns from each prompt version's `userMessage` and from composer prompt segments
4. Extracts prompt names from composer segments and converts them to camelCase keys
5. Groups versions with identical variable sets together
6. Sorts versions (latest first, then semver descending)
7. Writes the `declare module` augmentation file with `PromptVariableMap`, `ComposerVariableMap`, and `ComposerPromptMap`
8. Warns about any missing AI provider packages

## Integration with build tools

### package.json script

```json title="package.json"
{
  "scripts": {
    "generate": "promptly generate",
    "prebuild": "promptly generate"
  }
}
```

### CI/CD

Since the generated file should be committed to version control, you typically don't need to run codegen in CI. But if you want to verify types are up to date:

```bash
npx promptly generate
git diff --exit-code promptly-env.d.ts
```