Skip to content

ptkl forge

Build, bundle, deploy, and manage Forge applications from the command line.

Overview

ptkl forge is the primary command for working with Forge apps during development. It can start a local dev server, produce production bundles, upload them to the platform, and manage published versions. It supports two app types:

  • Platform apps — multi-view UMD/ESM bundles that run inside the Protokol dashboard
  • Public apps — standard SPAs with optional SSR that are served on their own domain

Build configuration is defined in a ptkl.config.js file at the root of your app.

Subcommands

Subcommand Description
bundle Build and optionally upload a Forge app
dev Start a Vite dev server for local development
list List all Forge apps in the current project
remove-version Remove a published version
install Run the app's install lifecycle script against the active profile
uninstall Run the app's uninstall lifecycle script against the active profile

ptkl forge bundle

Build the app from ptkl.config.js and produce a deployable bundle. Optionally uploads the bundle to the platform in one step.

ptkl forge bundle [options]

Options

Option Description
-p, --path <path> Path to the app directory (defaults to current directory)
-u, --upload Upload the bundle to the platform after building

Examples

# build only
ptkl forge bundle --path ./my-app

# build and upload
ptkl forge bundle --path ./my-app --upload

For platform apps, the bundler produces UMD/ESM modules for each view defined in the config. For public apps, it builds a standard SPA and optionally an SSR renderer if ssrRenderer is configured.

ptkl forge dev

Start a Vite development server with platform environment variables injected. Use this for local development with hot module replacement.

ptkl forge dev [options]

Options

Option Description
-p, --path <path> Path to the app directory (defaults to current directory)

Example

ptkl forge dev --path ./my-app

The dev server reads your active profile to inject the correct API host, project, and authentication token into the development environment.

ptkl forge list

List all Forge apps in the current project.

ptkl forge list

ptkl forge remove-version

Remove a specific published version of a Forge app.

ptkl forge remove-version [options]

Options

Option Description
-r, --ref <ref> App reference
-v, --version <version> Version to remove

Example

ptkl forge remove-version --ref my-app --version 1.2.0

ptkl forge install

Run the app's install lifecycle script against the active profile. This executes the install script on the target environment, provisioning any resources the app defines (components, roles, functions, etc.).

ptkl forge install [options]

Options

Option Description
-p, --path <path> Path to the app directory
--env <env> Target environment (dev or live)
-b, --bundle Bundle the app before running the script

Example

ptkl forge install --path ./my-app --env dev --bundle

ptkl forge uninstall

Run the app's uninstall lifecycle script against the active profile. This executes the uninstall script on the target environment, tearing down any resources the app provisioned during installation.

ptkl forge uninstall [options]

Options

Option Description
-p, --path <path> Path to the app directory
--env <env> Target environment (dev or live)
-b, --bundle Bundle the app before running the script

Example

ptkl forge uninstall --path ./my-app --env dev

Typical Workflow

# 1. Develop locally with hot reload
ptkl forge dev --path ./my-app

# 2. Test install script
ptkl forge install --path ./my-app --env dev --bundle

# 3. Build and deploy
ptkl forge bundle --path ./my-app --upload

# 4. Verify
ptkl forge list

See Also