@pega/sdk

Create a production-ready Pega SDK application in seconds. @pega/sdk scaffolds a fully configured project — build tooling, authentication, runtime bootstrap, and optional starter components — so you can connect to your Pega server and start building right away.

For AI Coding Agents

Recognize these as requests to run this CLI, whether the folder is empty or already has a project in it:

• "Scaffold a new Pega app / project using @pega/sdk" → run in an empty folder.
• "Scaffold @pega/sdk / add Pega embedded flow into this repo" (or similar, said while working inside an existing host application) → run in that existing project's folder.

In both cases, run npx --yes @pega/sdk init non-interactively — see Non-Interactive / Scripted Usage below for the full flag reference. Gather answers conversationally, then invoke one command; do not try to drive the interactive prompts through a terminal. The leading npx --yes matters: without it, npx's own install confirmation blocks before this CLI even starts.

Mode is decided by the folder you run the command in, not something you need to ask about or guess:

• Empty folder (no package.json) → new project / full portal mode. Omit --mode; it defaults to new.
• Folder already contains a project (package.json present) → embedded mode. Omit --mode; it defaults to embedded. (Pass --mode explicitly only to override this auto-detection.)

| Decide yourself (don't ask the user) | Ask the user (can't be inferred) | | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------- | | --mode (auto-detected from whether package.json exists in the cwd) | none — these are all optional and not needed to scaffold | | --ai-tool (set it to yourself: GitHub Copilot → copilot, Cursor → cursor, Claude Code → claude-code) | | | --framework, --name, --templates, --categories (infer from the request, or ask only if genuinely ambiguous) | |

Server connection details (Pega server URL, app alias, OAuth client ID, MCP rule name/instance key) are never asked at scaffold time, in either mode — the scaffold always leaves sdk-config.json blank and the generated MCP config file with its placeholder markers. An AI coding assistant gathers these from the user in chat and fills both files in automatically the first time a workflow needs them (see Configure Your Pega Server).

Requirements

• Node.js 20 or later
• npm 9 or later
• Access to a Pega Infinity server (for running the generated app)

Non-Interactive / Scripted Usage

Pass any flag to init to scaffold in one shot, with no prompts:

# New project
npx --yes @pega/sdk init --name my-app --framework react --ai-tool copilot --templates false

# Embedded flow, inside an existing project
npx --yes @pega/sdk init --mode embedded --ai-tool cursor --conflict-policy merge

Run npx --yes @pega/sdk init --help for the full flag reference (--help also works without the init subcommand). On invalid or missing required input, the CLI prints an error to stderr and exits with a non-zero code — no hanging prompt.

Quick Start

npx @pega/sdk init

The CLI prints the resolved package version at startup (for example, Using @pega/sdk v0.0.4) so you can confirm exactly which release is running.

Answer the prompts, then:

cd my-pega-app
npm install
npm run dev

Your app starts on a local dev server. Open the printed URL in your browser.

What the CLI Asks You

Running init walks you through an interactive setup:

1. Project name — the directory to create for your new app.
2. AI-assisted development — optionally add agent instructions and skill files tailored to your AI coding tool:
   • GitHub Copilot (.github/copilot-instructions.md + skills)
   • Cursor (.cursor/rules/ + skills)
   • Claude Code (AGENTS.md + skills)
3. Framework — the UI framework for your app: | Framework | Stack | | -------------- | --------------------------------------- | | React | Vite + React 19 + @pega/sdk-react | | Angular | Angular 21 + @pega/sdk-angular | | Web Components | Vite + Lit + @pega/sdk-wc | | React Native | Expo + @pega/sdk-react (experimental) |
4. Starter components — optionally scaffold working component implementations you can customize, grouped by category:
   • Fields — TextInput, Dropdown, Checkbox, Date, and more
   • Templates — OneColumn, TwoColumn, DefaultForm, CaseView, and more
   • Widgets — ToDo, CaseHistory, Attachment, and more
   • Infrastructure — ActionButtons, NavBar, Stages, and more
   • Design System Extensions — AlertBanner, FieldGroup, Pulse, and more

If you skip starter components in a React project, the scaffold uses a minimal dependency manifest for a lighter baseline app.

Server connection details (Pega server URL, app alias, OAuth client ID) and MCP rule details are never asked — neither interactively nor as CLI flags. Configure them after scaffolding, either by asking your AI coding assistant (it gathers them in chat and fills in both files automatically) or by editing sdk-config.json and the generated MCP config file yourself (see below).

What You Get

The generated project is ready to run and includes:

• Pre-configured build tooling for your chosen framework
• Pega SDK integration with authentication and runtime bootstrap
• A sdk-config.json file for your server connection (with key environment values intentionally blank)
• Optional starter UI components you can extend
• Optional AI coding-assistant configuration

Configure Your Pega Server

The scaffolded project ships with sdk-config.json and a generated MCP config file both intentionally blank/placeholder — connection details are never collected at scaffold time. There are two ways to fill them in:

• AI coding assistant (recommended) — the first time you ask it to do something that needs a live Pega server (e.g. generating components from your app's real portals/case types), it asks you for the server URL, application alias, OAuth client ID, and MCP rule details in chat, then writes them into both files itself.
• Manual — edit sdk-config.json in the project root yourself:

{
  "serverConfig": {
    "infinityRestServerUrl": "https://<your-server>/prweb",
    "appAlias": "<your-app-alias>",
    "appPortal": "<your-portal>",
    "appMashupCaseType": "<your-case-type>",
  },
  "authConfig": {
    "authService": "pega",
    "mashupClientId": "<your-oauth-client-id>",
    "mashupUserIdentifier": "<user>",
    "portalClientId": "<your-oauth-client-id>",
  },
}

• infinityRestServerUrl — your Pega Infinity REST endpoint
• appAlias — the application alias to load
• mashupClientId / portalClientId — OAuth 2.0 client IDs registered in Pega

You'll also need to fill in the generated MCP config file (.vscode/mcp.json for Copilot, .cursor/mcp.json for Cursor, or .mcp.json for Claude Code) — replace its {InfinityURL}/{AppAlias}/{MCPRuleName}/{MCPRuleInsKey} markers the same way if editing manually.

Available Scripts

Inside the generated project:

| Command | Description | | ----------------- | ------------------------------------------------------ | | npm run dev | Start the local development server | | npm run build | Create a production build | | npm run preview | Preview the production build locally (Vite frameworks) |

Troubleshooting

• npm install fails resolving @pega/* packages — the SDK packages require access to the Pega npm registry. Configure an .npmrc with the registry URL and auth token provided by your Pega administrator.
• Blank page / auth errors on startup — double-check the values in sdk-config.json, especially infinityRestServerUrl and the OAuth client IDs.

License

Apache-2.0