SDK Overview

The prompts-gpt Node.js SDK provides programmatic access to prompt management, execution runtime, sweep engine, and orchestration primitives. Use it to build custom automation, CI/CD integrations, or your own orchestration logic.

Installation

npm install prompts-gpt

Importing

import {
  // Client API
  PromptsGptClient,
  saveLocalCredentials,
  loadLocalCredentials,

  // Prompt sync
  syncPrompts,
  writePromptMarkdownFiles,
  writeAgentFiles,
  writePromptManifest,
  formatPromptMarkdown,

  // Execution runtime
  runPrompt,
  runBatch,
  loadRunConfig,
  detectProviders,
  resolveRunProvider,

  // Sweep engine
  sweepPrompt,
  acquireSweepLock,
  releaseSweepLock,

  // Orchestration
  orchestrateParallel,
  orchestratePipeline,
  orchestrateEval,

  // Utilities
  doctor,
  initRunConfig,
  isCI,
  isGitRepo,
  hasUncommittedChanges,
} from "prompts-gpt";

Module Structure

Module	Purpose
`prompts-gpt`	Main SDK entry — all exports
`prompts-gpt/cli`	CLI entry point (for binary execution)

Key Classes and Functions

Client API

Export	Description
<code>PromptsGptClient</code>	HTTP client for prompts-gpt.com API
`saveLocalCredentials()`	Save token to `.prompts-gpt/.credentials.json`
`loadLocalCredentials()`	Load stored credentials

Prompt Sync

Export	Description
<code>syncPrompts()</code>	Pull + write Markdown + write agent files + manifest
`writePromptMarkdownFiles()`	Write prompt Markdown files only
`writeAgentFiles()`	Write agent-specific files (AGENTS.md, .cursor/rules, etc.)
`writePromptManifest()`	Write manifest.json
`formatPromptMarkdown()`	Format a PromptPack as Markdown string

Execution Runtime

Export	Description
<code>runPrompt()</code>	Execute a single prompt
<code>runBatch()</code>	Execute multiple prompts
`loadRunConfig()`	Load `.prompts-gpt/config.json`
`detectProviders()`	Detect installed provider CLIs
`resolveRunProvider()`	Resolve which provider to use
`buildProviderCommand()`	Build the CLI command for a provider
`executeProviderCommand()`	Execute a provider CLI command

Sweep Engine

Export	Description
<code>sweepPrompt()</code>	Multi-iteration sweep engine
`acquireSweepLock()`	Acquire sweep lock file
`releaseSweepLock()`	Release sweep lock file
`forceReleaseSweepLock()`	Force-release a stale lock
`buildIterationPrompt()`	Build prompt with iteration context
`runPreFlight()`	Execute pre-flight checks

Orchestration

Export	Description
<code>orchestrateParallel()</code>	Race prompt across providers
<code>orchestratePipeline()</code>	Chain providers sequentially
<code>orchestrateEval()</code>	Execute + evaluate prompt
`buildEvalPrompt()`	Build evaluation prompt
`parseEvalResponse()`	Parse evaluation scores

Diagnostics

Export	Description
`doctor()`	System prerequisite check
`initRunConfig()`	Initialize a new config
`isCI()`	Detect CI environment
`isGitRepo()`	Check if cwd is a git repo

Type System

All TypeScript types are exported from the main module. See the Types Reference for complete documentation.

Error Handling

The SDK uses PromptsGptApiError for all API-related errors:

import { PromptsGptApiError } from "prompts-gpt";

try {
  await client.pullPrompts();
} catch (error) {
  if (error instanceof PromptsGptApiError) {
    console.error(`API Error: ${error.code} — ${error.message}`);
    console.error(`Recovery: ${error.recovery}`);
    console.error(`Request ID: ${error.requestId}`);
  }
}

Next Steps

Client API — PromptsGptClient reference
Runtime API — Execution functions
Sweep API — Sweep engine
Orchestration API — Multi-agent orchestration
Types Reference — All TypeScript types