Command line¶

PDK’s command line is pdk, on the PATH once installed (uv tool install pdk-perspective); in a clone of the repository it runs as uv run pdk <command> …. pdk --version prints the version. Every command that talks to the gateway accepts --url to override PDK_GATEWAY_URL for one call.

Exit codes: 0 success, 1 findings (errors in a validation or an inspection, a failed doctor check), 2 wrong usage.

pdk screenshot writes its PNG to --out when given. Without it, the file goes to <work>/_screenshots/ (<work> is PDK_WORK_DIR or work/ in the current folder; in a clone, the repository’s gitignored work/), named after the view path with / as __, plus __<component> when --component is given: PDK/Nav with root/Panel gives PDK__Nav__root_Panel.png. The command prints the path it wrote.

Perspective DevKit

usage: pdk [-h] [--version] [--perspective PERSPECTIVE]
           {doctor,init,validate,catalog,schemas,hook,gateway,pull,deploy,promote,delete,tags,pages,open,inspect,screenshot}
           ...

Positional Arguments¶

command: Possible choices: doctor, init, validate, catalog, schemas, hook, gateway, pull, deploy, promote, delete, tags, pages, open, inspect, screenshot

Named Arguments¶

--version: show program’s version number and exit
--perspective: bundle version to use (default: newest, or PDK_PERSPECTIVE_VERSION)

Sub-commands¶

doctor¶

check this machine’s setup (Ignition, schemas, Chromium, gateway, module, sandbox) and say how to fix what is missing

pdk doctor [-h] [--fix]

Named Arguments¶

--fix

also apply the local fixes: extract the schema bundle, download Chromium

Default: False

init¶

set up a folder for Claude Code with PDK: skill, subagents, MCP server, hook and a CLAUDE.md section (again after an upgrade, to refresh them)

pdk init [-h] [folder]

Positional Arguments¶

folder

the folder (default: the current one)

Default: '.'

validate¶

validate view.json files or directories

pdk validate [-h] [--project PROJECT] [--profile {hmi}] [--focus FOCUS]
             [--budget BUDGET] [--json] [--compile] [--url URL]
             paths [paths ...]

Positional Arguments¶

paths: view.json files or directories (searched recursively)

Named Arguments¶

--project

project dir or local gateway project name, for view/param references

--profile

Possible choices: hmi

extra lint rules (hmi-* design tokens)

--focus

expand diagnostics by code, component path or pointer prefix

--budget

output budget in tokens

Default: 6000

--json

machine-readable diagnostics

Default: False

--compile

also compile every script with the gateway’s Jython (E009); needs the module

Default: False

--url

–compile: gateway URL (default: PDK_GATEWAY_URL or http://127.0.0.1:8088)

catalog¶

components, props, bindings and events of the installed version

pdk catalog [-h] [--prop PROP] [--search SEARCH]
            [--topic {bindings,transforms,events,view,style,codes}]
            [--budget BUDGET]
            [type]

Positional Arguments¶

type: component id, short id or name (e.g. ia.display.label, label)

Named Arguments¶

--prop

nested prop path, e.g. columns[] or columns[].render

--search

find components by id, name or description

--topic

Possible choices: bindings, transforms, events, view, style, codes

reference card

--budget

output budget in tokens

Default: 3000

schemas¶

extract or list schema bundles

pdk schemas [-h] [--ignition-home IGNITION_HOME] [--modl MODL] [--out OUT]
            [--url URL]
            {extract,list,sync,functions}

Positional Arguments¶

action

Possible choices: extract, list, sync, functions

sync: compare with the gateway’s live catalog and add its third-party components; functions: save the gateway’s expression functions and system.* names next to the bundle, for B011 and E008

Named Arguments¶

--ignition-home: Ignition install dir (default: IGNITION_HOME or the standard path)
--modl: explicit Perspective .modl file
--out: bundle root (default: ./schemas or PDK_SCHEMAS_DIR)
--url: sync, functions: gateway URL (default: PDK_GATEWAY_URL or http://127.0.0.1:8088)

hook¶

Claude Code PostToolUse hook (reads the event JSON on stdin)

pdk hook [-h]

gateway¶

build, install, restart or check the pdk-gateway module

pdk gateway [-h] [--since SINCE] [--limit LIMIT] [--project PROJECT]
            [--view VIEW] [--restart] [--url URL]
            [--ignition-home IGNITION_HOME]
            {build,install,restart,health,scan,changes,sessions,logs}

Positional Arguments¶

action: Possible choices: build, install, restart, health, scan, changes, sessions, logs

Named Arguments¶

--since

changes/logs: only events after this sequence number

Default: 0

--limit

changes/scan/logs: at most this many events

Default: 50

--project

sessions: project (default: the sandbox); logs: filter by project

--view

logs: filter by view resource path, e.g. PDK/Demo

--restart

install: restart the gateway right after

Default: False

--url

gateway URL (default: PDK_GATEWAY_URL or http://127.0.0.1:8088)

--ignition-home

Ignition install dir (default: IGNITION_HOME or the standard path)

pull¶

download a view, a folder, stylesheet, a style class or a project script with its signature to work/<project>/<view path> (PDK_WORK_DIR)

pdk pull [-h] [--project PROJECT] [--force] [--url URL] path

Positional Arguments¶

path: view path or folder in the project (e.g. PDK/Menu), stylesheet, style-classes/<path>, scripts/<path>, or a local copy

Named Arguments¶

--project

project to read from (default: the sandbox)

--force

overwrite local edits

Default: False

--url

gateway URL (default: PDK_GATEWAY_URL or http://127.0.0.1:8088)

deploy¶

validate a local view (or the stylesheet) and write it, signed

pdk deploy [-h] [--resolved] [--budget BUDGET] [--url URL] path

Positional Arguments¶

path: local view folder or view.json, its sandbox view path (PDK/X), or the work/<project>/<view path> (PDK_WORK_DIR)/<sandbox>/_stylesheet folder

Named Arguments¶

--resolved

after a 409: write over the gateway version you reviewed and merged

Default: False

--budget

output budget in tokens

Default: 1500

--url

gateway URL (default: PDK_GATEWAY_URL or http://127.0.0.1:8088)

promote¶

copy a deployed PDK/<X> view to <X> in the sandbox or the target, signed

pdk promote [-h] [--to TO] [--to-project target] [--resolved]
            [--budget BUDGET] [--url URL]
            path

Positional Arguments¶

path: local folder of the deployed PDK/ view

Named Arguments¶

--to

target view path (default: the path without PDK/)

--to-project

copy to the target project (-Dpdk.target; ‘target’ or its name), not the sandbox

--resolved

after a 409: write over the gateway version you reviewed and merged

Default: False

--budget

output budget in tokens

Default: 1500

--url

gateway URL (default: PDK_GATEWAY_URL or http://127.0.0.1:8088)

delete¶

delete a pulled view on the gateway, only if nobody changed it since

pdk delete [-h] [--resolved] [--budget BUDGET] [--url URL] path

Positional Arguments¶

path: local view folder or view.json (it needs its .pdk-base.json)

Named Arguments¶

--resolved

after a 409: write over the gateway version you reviewed and merged

Default: False

--budget

output budget in tokens

Default: 1500

--url

gateway URL (default: PDK_GATEWAY_URL or http://127.0.0.1:8088)

tags¶

simulated tags under [provider]PDK/: list, read, write (with a quality), apply a tag export JSON, delete, alarms

pdk tags [-h] [--quality QUALITY] [--depth DEPTH] [--to TO] [--every EVERY]
         [--provider PROVIDER] [--url URL]
         {list,read,write,apply,delete,alarms,history} [items ...]

Positional Arguments¶

action: Possible choices: list, read, write, apply, delete, alarms, history
items: tag paths (without [provider] they hang from PDK/: Sandbox/Setpoint), a value to write, or the JSON file to apply

Named Arguments¶

--quality

write: quality to write with the value, e.g. Bad_Stale, Bad_Disabled

--depth

list: folder levels to walk (max 10)

Default: 1

--to

apply: folder under PDK/ to import into (default: PDK), or _types_/PDK for UDT definitions

--every

history: time between the values (30s, 1m, 2h, 1d)

Default: '1m'

--provider

history: tag history provider (default: the gateway’s only one)

--url

gateway URL (default: PDK_GATEWAY_URL or http://127.0.0.1:8088)

pages¶

routes of the sandbox’s page configuration (URL -> view): list, add, remove

pdk pages [-h] {list,add,remove} ...

Positional Arguments¶

action: Possible choices: list, add, remove

Sub-commands¶

list¶

one line per route, sorted by URL

pdk pages list [-h] [--url URL]

Named Arguments¶

--url: gateway URL (default: PDK_GATEWAY_URL or http://127.0.0.1:8088)

add¶

route a URL to a view of the sandbox (deployed first)

pdk pages add [-h] [--title TITLE] [--url URL] url view

Positional Arguments¶

url: URL path of the page, like /detail (not under /pdk/)
view: view path in the sandbox, like PDK/Detail

Named Arguments¶

--title: title of the page
--url: gateway URL (default: PDK_GATEWAY_URL or http://127.0.0.1:8088)

remove¶

remove a route to a view under PDK/

pdk pages remove [-h] [--url URL] url

Positional Arguments¶

url: URL path of the route to remove, like /detail

Named Arguments¶

--url: gateway URL (default: PDK_GATEWAY_URL or http://127.0.0.1:8088)

open¶

open a deployed view in headless Chromium and check that it renders

pdk open [-h] [--viewport VIEWPORT] [--url URL] path

Positional Arguments¶

path: local view folder or view.json under work/<project>/<view path> (PDK_WORK_DIR), or a view path in the sandbox (e.g. PDK/Menu)

Named Arguments¶

--viewport: WIDTHxHEIGHT or desktop, tablet, phone, wide (default: 1366x768); inspect takes several, comma-separated, one report each
--url: gateway URL (default: PDK_GATEWAY_URL or http://127.0.0.1:8088)

inspect¶

report the anomalies of a deployed view: layout, binding qualities, script errors, browser errors

pdk inspect [-h] [--focus FOCUS] [--query QUERY] [--expect EXPECT] [--act ACT]
            [--budget BUDGET] [--viewport VIEWPORT] [--url URL]
            path

Positional Arguments¶

path: local view folder or view.json under work/<project>/<view path> (PDK_WORK_DIR), or a view path in the sandbox (e.g. PDK/Menu)

Named Arguments¶

--focus

expand anomalies by code, component path or pointer prefix

--query

also print what was measured of these components: name paths (with their subtree), types, pointer prefixes, or * for all; comma-separated

--expect

expectations, ;-separated: ‘root/B below root/A; root/T width 100%; root/T text “Pump”; tag Sandbox/Setpoint = 42; alarm North/Level active’; failures are A001 diagnostics

--act

steps to perform before measuring, ;-separated: ‘click root/Save; type root/Name “P-2”; row root/Table 1; select root/Mode “Auto”; slide root/Level 7; key Enter; key root/Name Enter; hover root/X; double-click root/X; scroll root/List bottom; wait 500; tag Sandbox/Setpoint 42 [quality Bad_Stale]’; failures are A004

--budget

output budget in tokens

Default: 1500

--viewport

WIDTHxHEIGHT or desktop, tablet, phone, wide (default: 1366x768); inspect takes several, comma-separated, one report each

--url

gateway URL (default: PDK_GATEWAY_URL or http://127.0.0.1:8088)

screenshot¶

PNG of a deployed view, or of one of its components

pdk screenshot [-h] [--component COMPONENT] [--out OUT] [--act ACT]
               [--compare BEFORE.png] [--viewport VIEWPORT] [--url URL]
               path

Positional Arguments¶

path: local view folder or view.json under work/<project>/<view path> (PDK_WORK_DIR), or a view path in the sandbox (e.g. PDK/Menu)

Named Arguments¶

--component: name path (root/Panel/Label) or DOM path (C.0:1); popup:<id>/root/… once –act opened the popup
--out: PNG file to write (default: <work>/_screenshots/<view>[__<component>].png, <work> being PDK_WORK_DIR or work/)
--act: steps performed before capturing, same grammar as inspect –act (to capture a popup or a state after typing); a failing step is A004 and no PNG
--compare: PNG taken before, of the same view, viewport and component: reports the % of pixels that changed and where, and writes the changed pixels in red to <out>__diff.png
--viewport: WIDTHxHEIGHT or desktop, tablet, phone, wide (default: 1366x768); inspect takes several, comma-separated, one report each
--url: gateway URL (default: PDK_GATEWAY_URL or http://127.0.0.1:8088)