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.

bun

bunx promptly generate

npm

npx promptly generate

yarn

yarn dlx promptly generate

pnpm

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

# 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:

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:

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:

// 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:

'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>:

'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

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:

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