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.

Log in with your browser (OAuth, the default):

ptkl profile new -n production -h https://api.example.com -P <project-uuid>

For scripts and CI, log in as an API user with --legacy. API-user credentials come from ptkl api-users new or the dashboard. The secret is prompted securely unless you pass a value (not recommended: it lands in shell history).

ptkl profile new --legacy -n ci -u <api-user> -P my-project -h https://api.example.com

Email/password login is no longer available in the CLI; use the OAuth login.

Options

• -n, --name <name> - Profile name (e.g., "production", "staging")
• -P, --project <project> - Project identifier
• -h, --host <host> - API host URL
• --legacy - Use API-user credentials (username + secret) instead of OAuth
• -u, --username <username> - API-user username (with --legacy)
• -p, --password [secret] - API-user secret (with --legacy; prompted if omitted)

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 [name]                    # OAuth browser login
ptkl profile auth [name] --legacy -u <api-user>   # API-user login (secret prompted)

Options (legacy)

• -u, --username <username> - API-user username (defaults to the stored one)
• -p, --password [secret] - API-user secret (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

OAuth login (default)

OAuth browser login is the default for profile new and profile auth:

ptkl profile new -n dev -h https://api.example.com -P <project-uuid>   # create + log in
ptkl profile auth [name]                                               # log in again (default: active profile)
ptkl profile logout [name]                                             # revoke + clear tokens

After a successful login the browser tab is redirected to the OAuth guide (https://docs.protokol.io/platform/oauth/); failures show an error page with the retry command.

The flow is authorization code + PKCE with a loopback redirect on 127.0.0.1. -P must be a project UUID (one login covers one project). Options: --no-browser prints the URL instead of opening a browser, --port fixes the loopback port (default: random), --client-id overrides the client (default: the profile's stored client, $PTKL_OAUTH_CLIENT_ID, then the built-in first-party CLI client), --scope <list> replaces the default scope and --add-scope <list> extends it (comma-separated permission names; pattern:<regex> for a regex).

If OAuth is not enabled on the host the command fails with a pointer to --legacy; there is no silent fallback.

Legacy and CI. --legacy (implied by -u, -p or -t) logs in as an API user (/v1/user/api/auth) or takes a token directly, e.g. ptkl profile auth -t $TOKEN. For CI use API-user tokens with --legacy -t.

Default scope is a least-privilege toolkit preset (src/lib/oauth/ScopePreset.ts), further limited by your own permissions in the project: apps, functions, components, templates, thunder, ratchet (read/inspect), users and roles (list), API users (edit base_users for list/get/edit/revoke-secret, manage_secrets base_users for new/new-secret), global env (read), and dev env_access (non-live environments need <env> env_access; dev is the default — add others with --add-scope "<env> env_access"). Scope never grows by itself: re-run ptkl profile auth after creating resources whose per-resource permissions you need.

Access tokens (15 min) refresh transparently when a command starts, serialized across processes by a per-profile lock in ~/.ptkl (the rotated refresh token is saved); long-running commands such as watch modes refresh only at start. If the session expired or was revoked you are asked to log in again. profile inspect masks tokens.

Not available with OAuth profiles (routes OAuth does not admit; the CLI says so on a 403): workflow, sandbox, kortex, integration(s), satellite, logs, forge, project administration, and user and role changes unless you --add-scope "edit base_users". Use a --legacy profile for these.

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.