Protokol Toolkit

The Protokol Toolkit (ptkl) is a development-time CLI for managing your Protokol platform project. It handles authentication, app bundling & deployment, component building, role and user management, IDL validation, and TypeScript code generation.

Note

ptkl (toolkit) and @ptkl/sdk are separate packages. The toolkit is a dev-time CLI — it is never imported or used at runtime. The SDK is a runtime library used inside expressions and application code. You do not need the toolkit to use the SDK, and vice versa.

Installation

npm install -g @ptkl/toolkit

Quick Start

# 1. Initialize the toolkit (creates ~/.ptkl/)
ptkl init

# 2. Create a profile for your project
ptkl profile new \
  --name my-project \
  --username admin@example.com \
  --password \
  --project my-project \
  --host https://api.protokol.io

# 3. You're ready — try listing your Forge apps
ptkl forge list

Global Options

Option	Description
`--profile <name>`	Override the active profile for any command. When omitted, uses the profile marked as active.

Commands

Command	Description
`ptkl init`	Initialize the toolkit
`ptkl profile`	Manage authentication profiles
`ptkl forge`	Build, bundle, deploy, and manage Forge apps
`ptkl component`	Build and live-reload component templates
`ptkl functions`	List and inspect platform functions
`ptkl role`	Create, edit, and delete roles
`ptkl api-users`	Manage API users and secrets
`ptkl users`	Invite and remove project users
`ptkl generate-types`	Generate TypeScript types from component IDLs
`ptkl validate-idl`	Validate values against IDL definitions

`ptkl init`

Creates the ~/.ptkl/ directory and an empty profiles.json file. Run this once before using any other command.

ptkl init

If the directory already exists, the command is a no-op.

Profiles

Every command that talks to the Protokol API needs an authenticated profile. A profile stores the API host, project, username, and authentication token. You can have multiple profiles and switch between them.

See ptkl profile for full documentation.

App Configuration — `ptkl.config.js`

Several commands (forge bundle, forge dev, component build) read a ptkl.config.js file from the app's root directory. This file defines metadata, entry points, and build options.

See App Manifest for the full configuration reference.