Skip to content

ptkl satellite

Manage Satellites — custom JSON-RPC integrations deployed to the platform's integrations gateway.

Overview

A satellite is a project's own custom integration: a JSON-RPC 2.0 service (mandatory system.health/system.capabilities methods) deployed and versioned through the platform, then invoked the same way a built-in integration is. ptkl satellite maps 1:1 onto the SDK Satellites client (@ptkl/sdk/beta), which talks to the integrations gateway (host/luma/integrations) — see Toolkit Overview → The Gateway Model.

ptkl satellite execute and ptkl integration run are the same door — both hit satellites/{id}/commands/{method}/execute. Use satellite for template/version management and integration run when you're already working with an id in the generic-integration context.

Subcommands

Subcommand Description
templates list List all satellite templates for the current project
templates create Create a satellite template, optionally with an initial schema version
templates get <id> Get a satellite template by id
templates delete <id> Delete a satellite template
versions list <id> List all schema versions for a template
versions create <id> Create a new schema version for a template
deploy <id> Deploy a schema version to an environment
rollback <id> Roll a template back to a previous schema version in an environment
permissions <id> List the permission exports declared by a template's active schema
logs <id> Fetch logs for a template
execute <id> <command> Invoke a JSON-RPC command on a satellite

ptkl satellite templates

ptkl satellite templates list
ptkl satellite templates get <id>
ptkl satellite templates delete <id>

ptkl satellite templates create

ptkl satellite templates create -d <json>
Option Description
-d, --data <json> { "template": {...}, "schema"?: {...} } (required) 
ptkl satellite templates create --data '{
  "template": { "id": "crm-satellite", "name": "CRM Satellite" }
}'

ptkl satellite versions

ptkl satellite versions list <id>

ptkl satellite versions create

ptkl satellite versions create <id> -d <json>
Option Description
-d, --data <json> { "schema_version", "schema"?, "permissions"?, "jsonrpc_commands"?, "workflownodes"? } (required) 
ptkl satellite versions create crm-satellite --data '{
  "schema_version": "1.1.0",
  "jsonrpc_commands": ["echo", "sync-contacts"]
}'

ptkl satellite deploy

Deploy a template's schema version to an environment.

ptkl satellite deploy <id> -s <version> --target-env <env>
Option Description
-s, --schema-version <version> Schema version to deploy (required)
--target-env <env> dev | live (required) 
ptkl satellite deploy crm-satellite --schema-version 1.1.0 --target-env dev

ptkl satellite rollback

Roll a template back to a previous schema version.

ptkl satellite rollback <id> -s <version> --target-env <env>

Same options as deploy.

ptkl satellite rollback crm-satellite --schema-version 1.0.0 --target-env live

ptkl satellite permissions

List the permission exports declared by a template's active schema.

ptkl satellite permissions crm-satellite

ptkl satellite logs

ptkl satellite logs <id> [--since <timestamp>]

ptkl satellite logs crm-satellite --since 2026-07-17T00:00:00Z

ptkl satellite execute

Invoke a JSON-RPC command on a satellite. Same door as ptkl integration run.

ptkl satellite execute <id> <command> [-p <json>]
Option Description
-p, --params <json> Execute payload { inputs, context, session, caller_prn }, defaults to {} 
ptkl satellite execute crm-satellite sync-contacts --params '{"inputs":{"since":"2026-07-01"}}'

Typical Workflow

# 1. Create a template and an initial schema version
ptkl satellite templates create --data '{"template":{"id":"crm-satellite","name":"CRM Satellite"}}'
ptkl satellite versions create crm-satellite --data '{"schema_version":"1.0.0","jsonrpc_commands":["echo"]}'

# 2. Deploy to dev, exercise it
ptkl satellite deploy crm-satellite --schema-version 1.0.0 --target-env dev
ptkl satellite execute crm-satellite echo --params '{"inputs":{"message":"hello"}}'

# 3. Watch logs, then promote
ptkl satellite logs crm-satellite
ptkl satellite deploy crm-satellite --schema-version 1.0.0 --target-env live

See Also