Protokol Toolkit

A command-line toolkit for managing Protokol platform applications, profiles, functions, and components.

Installation

npm install -g @ptkl/toolkit

Getting Started

1. Initialize the Toolkit

Before using the toolkit, initialize it to create the configuration directory:

ptkl init

This creates a ~/.ptkl directory where profiles and settings are stored.

2. Create a Profile

A profile stores your authentication credentials and connection settings for a Protokol instance.

Secure Method (Recommended)

Omit the password or use --password flag without a value to be prompted securely:

ptkl profile new \
  -n production \
  -u [email protected] \
  -P my-project \
  -h https://api.example.com \
  --password

You'll be prompted to enter your password securely (hidden input).

With Password in CLI (Not Recommended)

ptkl profile new \
  -n production \
  -u [email protected] \
  -P my-project \
  -h https://api.example.com \
  --password "myPassword"

⚠️ Security Warning: This will show a warning as the password may be visible in shell history.

Options

• -n, --name <name> - Profile name (e.g., "production", "staging")
• -u, --username <username> - Email or API username
• -P, --project <project> - Project identifier
• -h, --host <host> - API host URL
• -p, --password [password] - Password (optional value for secure prompt)

Profile Management

List All Profiles

ptkl profile list

Shows all available profiles. The currently active profile is marked with *.

View Current Profile

ptkl profile

Switch to a Different Profile

ptkl profile use staging

Sets staging as the active profile for all subsequent commands.

Inspect Profile Details

ptkl profile inspect production

Re-authenticate a Profile

If your token expires or you need to update credentials:

ptkl profile auth --password

Or for a specific profile:

ptkl profile auth --profile production --password

Options

• -p, --password [password] - Password (omit value for secure prompt)
• -t, --token <token> - Directly provide a token
• -P, --project <project> - Update the project

Delete a Profile

ptkl profile delete staging

Using the --profile Flag

You can override the active profile for any command using the global --profile flag:

ptkl --profile production apps upload -a app -d ./my-app

Forge

Commands for building and running Protokol Forge apps locally.

ptkl forge dev

Start a local development server for a forge app with hot module replacement.

ptkl forge dev -p <path> [options]

Options

| Flag | Description | |------|-------------| | -p, --path <path> | (required) Path to the app directory | | --view <view> | Which view to serve (defaults to main) | | --platform-url <url> | Platform UI URL for consent/permission flows | | -m, --mode <mode> | Vite mode (defaults to development) | | --env <env> | Target environment (dev or live) |

Multi-view development

Forge apps can declare multiple views in ptkl.config.js:

export default {
  name: 'my-app',
  views: {
    main: path.resolve(__dirname, 'src/main.tsx'),
    'product-details': {
      entry: path.resolve(__dirname, 'src/productDetails.tsx'),
      access: 'public',
      permissions: ['read my-integration::items'],
    },
  },
}

By default, ptkl forge dev serves the main view. Use --view to serve a different one:

# Serve the main platform view (default)
ptkl forge dev -p .

# Serve a public view for standalone testing
ptkl forge dev -p . --view product-details

The --view flag swaps the entry point in the app's index.html so Vite serves the selected view with full HMR. Each view runs as a standalone app on its own dev server.

Embeddable platform views (not main, not public) are automatically built in watch mode and published to the local dev hub for cross-app testing via AppView.

ptkl forge bundle

Build and optionally upload a forge app bundle.

ptkl forge bundle -p <path> [options]

Options

| Flag | Description | |------|-------------| | -p, --path <path> | (required) Path to the app directory | | -u, --upload | Upload the bundle after building | | -m, --mode <mode> | Vite build mode (defaults to production) |

ptkl forge list

List all forge apps in the current profile's project.

ptkl forge list

ptkl forge install / ptkl forge uninstall

Dry-run install or uninstall scripts locally against the active profile.

ptkl forge install -p <path> [--env dev|live] [-b] [--var KEY=value]
ptkl forge uninstall -p <path> [--env dev|live] [-b] [--var KEY=value]

| Flag | Description | |------|-------------| | -p, --path <path> | (required) Path to the app directory | | --env <env> | Run for a specific env only (omit to run both) | | -b, --bundle | Build the bundle before running the script | | --var <key=value> | Set one app variable ($variables) for the run. Repeatable. | | --vars <list> | Set several at once: 'KEY=value;KEY2=value2'. Repeatable. | | --vars-file <path> | JSON file of variables — flat, or env-keyed { "dev": {...}, "live": {...} } |

On the platform, the install script reads the app's stored variables for the environment through the $variables global. Locally there is no app record, so pass them in:

ptkl forge install -p ./my-app --env dev \
  --var WEBHOOK_URL=https://staging.example.com/hook \
  --var MAX_RETRIES=3

Values are parsed as JSON when valid (3 → number, true → boolean, {"a":1} → object) and kept as strings otherwise. Sources merge in order --vars-file → --vars → --var, so a base file can be overridden per run. These flags affect the local dry run only — they never write to the deployed app's variables.

ptkl forge remove-version

Remove a specific version of a forge app.

ptkl forge remove-version -r <ref> -v <version>

Version

Current version: 0.7.0

License

GNU General Public License v3.0 (GPL-3.0)

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Any modifications or derivative works must also be licensed under GPL-3.0 and the source code must be made available.