Plugin CLI Commands

The Synapse SDK provides CLI commands for plugin development and execution.

synapse plugin run

Run a plugin action with various execution modes.

Usage

synapse plugin run <action> [OPTIONS]

Arguments

Argument	Description
`action`	Action to run (e.g., test, train, deploy, infer)

Options

Option	Short	Description
`--plugin`	`-p`	Plugin code. Auto-detects from config.yaml if not provided
`--path`		Plugin directory (default: current)
`--params`		JSON parameters to pass to the action
`--mode`	`-m`	Executor mode: local, task, job, or remote
`--ray-address`		Ray cluster address (for task/job modes)
`--gpus`		Number of GPUs to request
`--cpus`		Number of CPUs to request
`--lang`	`-l`	Language for i18n log messages (ISO 639-1, e.g., 'en', 'ko')
`--debug/--no-debug`		Debug mode (default: enabled)
`--debug-sdk`		Bundle local SDK with upload (for SDK development)

Executor Modes

Mode	Description
`local`	In-process execution (best for debugging)
`task`	Ray Actor execution (no log streaming)
`job`	Ray Jobs API with log streaming (recommended for remote)
`remote`	Run via Synapse backend API (requires auth)

Examples

# Basic execution
synapse plugin run test
synapse plugin run test --mode local

# With GPU allocation
synapse plugin run test --mode task --gpus 1

# With parameters
synapse plugin run train --mode job --params '{"epochs": 10}'

# With language selection (i18n)
synapse plugin run train --lang=ko --params '{"epochs": 10}'
synapse plugin run train -l en  # Short form

# Language with different execution modes
synapse plugin run train --mode local --lang=ko
synapse plugin run train --mode task --lang=ko
synapse plugin run train --mode job --lang=ko

# Remote execution
synapse plugin run deploy --mode remote

synapse plugin publish

Publish a plugin release to Synapse.

Usage

synapse plugin publish [OPTIONS]

Options

Option	Short	Description
`--path`	`-p`	Plugin directory (default: current)
`--config`	`-c`	Config file path
`--host`		Synapse API host
`--token`	`-t`	Access token
`--dry-run`		Preview without uploading
`--debug`		Debug mode (bypasses backend validation)
`--yes`	`-y`	Skip confirmation

Examples

synapse plugin publish
synapse plugin publish -p ./my-plugin --dry-run

synapse plugin create

Create a new plugin from template.

Usage

synapse plugin create [OPTIONS]

Options

Option	Short	Description
`--path`	`-p`	Output directory (default: current)
`--name`	`-n`	Plugin name
`--code`		Plugin code (slug)
`--category`	`-c`	Plugin category
`--yes`	`-y`	Skip confirmation
`--template`		Backend action template `<category>/<action>[@<version>]` (default version: the active one)
`--answers`		Template intake answers: a JSON object or `@file.json`
`--template-bundle`		Render this bundle zip instead of downloading it (offline; needs `@<version>`)
`--host`		Synapse API host for `--template` (default: from `synapse login`)
`--token`	`-t`	Access token for `--template` (default: from `synapse login`)

Without a TTY nothing is prompted: --name and --code are required, and an existing directory is only replaced with --yes.

From a backend action template

With --template the plugin gets the one action of a backend action template (/v2/plugin-action-templates/). The SDK downloads the template bundle (checked against its sha256), checks --answers against the template's intake (question kinds, options and when conditions) and renders the bundle with the same code as the SDK category templates:

the SDK base templates (config.yaml, README.md, pyproject.toml, plugin/__init__.py, ...),
the bundle's config.yaml.j2 merged over the base config.yaml (top-level keys replace the base ones),
the bundle's requirements.txt.j2 instead of the base one,
the bundle's plugin/*.j2 files.

Template variables are those of the category templates (name, code, version, category, data_type, ...) plus each answer under its question id and all answers as answers. An answer id that collides with one of those variables is rejected. The action records the template in config.yaml:

actions:
  train:
    entrypoint: plugin.train.TrainAction
    method: job
    template:
      id: neural_net/train
      version: 3
      answers: {model_source: upload}

With --template-bundle the answers are not checked (the intake lives on the backend).

Examples

synapse plugin create
synapse plugin create --name "My Plugin" --category neural_net
synapse plugin create --name "My Plugin" --code my-plugin --template neural_net/train \
    --answers '{"model_source": "upload"}'
synapse plugin create --name "My Plugin" --code my-plugin --template neural_net/train@3 --answers @answers.json

synapse plugin add-action

Add the action of a backend action template to an existing plugin.

Usage

synapse plugin add-action --template <category>/<action>[@<version>] [OPTIONS]

Options

Option	Short	Description
`--template`		Backend action template `<category>/<action>[@<version>]`
`--answers`		Template intake answers: a JSON object or `@file.json`
`--path`	`-p`	Plugin directory (default: current)
`--force`		Replace the action and overwrite existing action files
`--template-bundle`		Render this bundle zip instead of downloading it (offline; needs `@<version>`)
`--host`		Synapse API host (default: from `synapse login`)
`--token`	`-t`	Access token (default: from `synapse login`)

The template must be for the plugin's category. The command renders the bundle's plugin/*.j2 files into plugin/, adds the action from the bundle's config.yaml.j2 (with its template record) to config.yaml — appended to the actions block so the rest of the file, comments included, stays as written — and appends the bundle's requirements that requirements.txt lacks. Other top-level keys of the bundle config are not applied. Nothing is written when the action already exists in config.yaml or one of its files exists, unless --force is given.

Examples

synapse plugin add-action --template neural_net/inference --answers @answers.json
synapse plugin add-action --template neural_net/train@4 --answers '{"model_source": "upload"}' --force

synapse plugin check

Check plugin actions against the harness and guardrail of the backend action template they follow (actions.<name>.template in config.yaml). Actions without template are not checked.

The template version's intake, harness and guardrail are read from the backend registry (/v2/plugin-action-templates/) with the synapse login credentials. If the backend is not configured, not reachable, or does not have that version, the SDK defaults for the (category, action) are used — the action module and requirements.txt must exist and the entrypoint must inherit the SDK base class; the guardrail is empty. The output says when this happens.

Usage

synapse plugin check [OPTIONS]

Options

Option	Short	Description
`--path`	`-p`	Plugin directory (default: current)
`--action`	`-a`	Check only this action
`--smoke`		Also run each action with the harness smoke params (runs plugin code locally, like `plugin run --mode local`)
`--json`		Print one JSON document instead of text
`--host`		Synapse API host (default: from `synapse login`)
`--token`	`-t`	Access token (default: from `synapse login`)

Checks

Check	Severity	Codes
`harness.required_files` exist	warning	`harness.required_file_missing`
entrypoint class inherits `harness.entrypoint_base` (AST, through the plugin's modules)	warning	`harness.entrypoint_base_mismatch`, `harness.entrypoint_base_unresolved`, `harness.entrypoint_not_found`, `harness.entrypoint_not_class`, `harness.entrypoint_missing`
no import of `guardrail.forbidden_imports` (AST)	error	`guardrail.forbidden_import`; `guardrail.dynamic_import` (warning)
package indexes / direct URL / VCS requirements in `requirements.txt` and `package_manager_options` are allowed	error	`guardrail.disallowed_index`, `guardrail.disallowed_source`, `guardrail.disallowed_trusted_host`
`container.resources` and the action's `serve_options.ray_actor_options` within `guardrail.resources`	error	`guardrail.resource_exceeded`
recorded answers match the intake	warning	`template.answers_invalid`
`--smoke`: the action runs within `smoke.timeout_seconds`; params/result match `params_schema`/`result_schema`	warning	`harness.smoke_failed`, `harness.smoke_timeout`, `harness.smoke_params_invalid`, `harness.params_schema_mismatch`, `harness.result_schema_mismatch`

A package index is allowed when it is the internal index (PIP_INDEX_URL, PIP_EXTRA_INDEX_URL, UV_INDEX_URL, UV_EXTRA_INDEX_URL of the environment) or a package_index of a guardrail.allow entry that the recorded answers enable (an intake option's guardrail key). Direct URL and VCS requirements need their host in an enabled entry's hosts.

The import check only sees what is statically visible: __import__() / importlib.import_module() with a non-literal argument is reported as a warning, and exec/eval or imports inside installed packages are not detected.

The command exits with 1 when there is an error (guardrail violation). Warnings (harness not met) do not change the exit code. The backend runs the same static check at publish time: errors reject the release, warnings are stored with it.

JSON output

{
  "schema_version": 1,
  "ok": false,
  "plugin_dir": "/workspace/my-plugin",
  "notes": [],
  "actions": [
    {"action": "train", "template": {"id": "neural_net/train", "version": 3},
     "source": "backend", "skipped": null, "smoke": null}
  ],
  "findings": [
    {"code": "guardrail.forbidden_import", "severity": "error",
     "message": "Import of subprocess is forbidden by the template guardrail (subprocess)",
     "file": "plugin/train.py", "line": 3, "column": 1, "action": "train"}
  ]
}

source is backend or sdk-default; smoke is null (not requested), not_configured, passed or failed. file is relative to the plugin directory; line/column are 1-based.

Examples

synapse plugin check
synapse plugin check --smoke
synapse plugin check --json --action train

synapse plugin update-config

Auto-discover actions and sync to config.yaml.

Usage

synapse plugin update-config [OPTIONS]

Options

Option	Short	Description
`--path`	`-p`	Plugin directory (default: current)
`--config`	`-c`	Config file path

Examples

synapse plugin update-config
synapse plugin update-config -p ./my-plugin

synapse plugin job get

Get job details.

Usage

synapse plugin job get <job_id> [OPTIONS]

Options

Option	Short	Description
`--host`		Synapse API host
`--token`	`-t`	Access token

Examples

synapse plugin job get 123

synapse plugin job logs

Get job logs.

Usage

synapse plugin job logs <job_id> [OPTIONS]

Options

Option	Short	Description
`--follow`	`-f`	Follow log output (stream)
`--host`		Synapse API host
`--token`	`-t`	Access token

Examples

synapse plugin job logs 123
synapse plugin job logs 123 -f

synapse plugin run​

Usage​

Arguments​

Options​

Executor Modes​

Examples​

synapse plugin publish​

Usage​

Options​

Examples​

synapse plugin create​

Usage​

Options​

From a backend action template​

Examples​

synapse plugin add-action​

Usage​

Options​

Examples​

synapse plugin check​

Usage​

Options​

Checks​

JSON output​

Examples​

synapse plugin update-config​

Usage​

Options​

Examples​

synapse plugin job get​

Usage​

Options​

Examples​

synapse plugin job logs​

Usage​

Options​

Examples​

synapse plugin run

Usage

Arguments

Options

Executor Modes

Examples

synapse plugin publish

Usage

Options

Examples

synapse plugin create

Usage

Options

From a backend action template

Examples

synapse plugin add-action

Usage

Options

Examples

synapse plugin check

Usage

Options

Checks

JSON output

Examples

synapse plugin update-config

Usage

Options

Examples

synapse plugin job get

Usage

Options

Examples

synapse plugin job logs

Usage

Options

Examples