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.

--env is a per-subcommand option, not a global one

--env <dev|live> is not a program-level flag — it must come after the subcommand, e.g. ptkl project list --env live, not ptkl --env live project list (the latter fails with unknown option '--env'). It is attached to new and extended subcommands built on the shared scaffold and defaults to dev; pre-existing commands (logs, apps, component, role, api-users, users, profile) do not accept it. generate-types and validate-idl carry their own pre-existing --env <env> (which IDL-fetch / validation environment to use) that predates the scaffold. Note also that forge dev/forge install/forge uninstall carry an unrelated --env flag that selects which environment's local lifecycle scripts to run — not the same option.

The Gateway Model

ptkl does not talk to platform microservices directly — it talks to two gateways, over one authenticated profile:

The native platform gateway (PlatformBaseClient, host/v1/... and host/{service}/...) — native platform routes (users, roles, api-users, projects, components, functions, forge, thunder, ratchet, workflow, sandbox, kortex, transactions/billing, …) plus every proxied microservice reachable under a {service}/ prefix.
The integrations gateway (IntegrationsBaseClient, host/luma/integrations/...) — REST and JSON-RPC routes for installed integrations (payments, mail, DMS, timber, Serbia fiscalization) and custom satellites.

Every new API the toolkit gains is not a new transport or a new credential — it is a route group already reachable through one of these two gateways, wrapped by an SDK client that extends PlatformBaseClient or IntegrationsBaseClient, surfaced by a command that resolves the active profile and calls that client. No ptkl command talks to the platform via raw axios; every command goes through an @ptkl/sdk/beta client. See TypeScript SDK → SDK-first & the Gateway Model for the client-level detail.

Commands

Identity & access

Command	Description
`ptkl init`	Initialize the toolkit
`ptkl profile`	Manage authentication profiles
`ptkl api-users`	Manage API users and secrets
`ptkl role`	Create, edit, and delete roles
`ptkl users`	Invite and remove project users

Project control-plane

Command	Description
`ptkl project`	Projects, workspaces, invites, billing-modes
`ptkl template`	Search, install, and upgrade project templates
`ptkl config`	Get/set user configuration

Build surface

Command	Description
`ptkl component`	Build and live-reload component templates, models, policies, extensions
`ptkl functions`	List, inspect, run, and create platform functions
`ptkl forge`	Build, bundle, deploy, and manage Forge apps — services, variables, domains, `run`
`ptkl generate-types`	Generate TypeScript types from component IDLs
`ptkl validate-idl`	Validate values against IDL definitions

Data & connections

Command	Description
`ptkl ratchet`	Manage external database connections and run queries
`ptkl thunder`	Generic entity storage on the platform's own database

DMS (media/document storage) is an integration, not a standalone data command — see ptkl integration dms below.

Execution

Command	Description
`ptkl workflow`	CRUD, trigger/publish/install, and execution control (history, running, pause/resume/kill/restart, errors)
`ptkl sandbox`	Spark and runtime management

AI

Command	Description
`ptkl kortex`	Chat TUI plus the agent/knowledge-base/document/conversation management subtree

Billing

Command	Description
`ptkl billing`	Subscriptions, invoices, credit balance/top-ups, usage pricing, billing-mode overrides

Integrations

Command	Description
`ptkl integration`	Integration lifecycle, generic JSON-RPC passthrough, and typed interfaces — `payments`, `mail`, `dms`, `timber`, `serbia`
`ptkl satellite`	Deploy, version, and execute custom JSON-RPC satellites

Legacy

Command	Description
`ptkl apps`	Deprecated app management (superseded by `forge`) — kept for backward compatibility
`ptkl logs`	Back-compat alias of `ptkl integration timber query` — kept for existing scripts, keeps its original flag set

`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.