Get Started
This walkthrough starts in an empty folder and ends with a tested plugin installed in Designer. It assumes the CLI is installed and your environment is active. Go to Set Up Environment if not.
Initialize the Workspace
sdk-workspace-init turns the current folder into an SDK workspace.
mkdir DemoPackage
cd DemoPackage
ayx_plugin_cli sdk-workspace-initThe command prompts for each value. Pass flags to skip the prompts:
ayx_plugin_cli sdk-workspace-init --package-name DemoPackage --tool-category "Demo Menu" --description "Demo plugins" --author "Jane Developer" --company "Example Co" --backend-language pythonValue | Meaning |
|---|---|
Package Name | Name of the workspace package and of the YXI it builds. |
Tool Category | The Designer tool palette tab where the plugins appear. |
Description | Shown to users when they install the YXI. |
Author | Who wrote the plugins. |
Company | Who owns the plugins. |
Back-end Language | |
The output ends with the workspace location, a note that settings live in ayx_workspace.json, and a "Generating config files" message. The folder now contains ayx_workspace.json, backend/, configuration/, pyproject.toml, and README.md.
Open ayx_workspace.json and check backend_language_settings.python_version against your target Designer release. Change it now if it differs.
Add a Plugin
ayx_plugin_cli create-ayx-plugin --tool-name MyFirstPlugin --tool-type single-input-single-outputWithout flags, the CLI prompts for the plugin name, type, whether it writes data to an external destination, description, version, an optional DCM namespace (press Enter to leave it empty), and whether to skip the configuration panel.
Choose the plugin type that matches the data flow:
Type | Shape |
|---|---|
| No input anchors. Generates data. |
| Input anchor only. Consumes data. |
| One input, one output (default). |
| Several input anchors. |
| Several output anchors. |
| An input anchor that may be unconnected. |
| One input anchor that accepts several connections. |
Choose carefully. Changing the type later means reworking the anchor handling and the generated configuration.
To skip the configuration panel (and the Node requirement), add --omit-ui:
ayx_plugin_cli create-ayx-plugin --tool-name MyFirstPlugin --tool-type single-input-single-output --no-writes-output-data --description "Passes data through" --tool-version 1.0 --omit-ui The command creates the plugin’s Python module, tests, and configuration files, and registers the plugin in ayx_workspace.json. Unless you skip it, it also generates the configuration panel.
Generate or Refresh Scaffolding When Needed
create-ayx-plugin already generates tests and UI. Use these commands to regenerate them later, for example after the template changes:
ayx_plugin_cli generate-tests --tool-name MyFirstPlugin
ayx_plugin_cli generate-ui --tool-name MyFirstPluginRegenerating tests overwrites the generated test file, so keep hand-written tests in separate files.
Implement the Plugin
Open backend/ayx_plugins/my_first_plugin.py. The generated class already passes input to output. Add your logic in the callbacks, for example, on_record_batch. The Example Plugins page shows common patterns.
Update and Run the Tests
The generated tests expect the pass-through behavior. Edit the expected data so it matches what your plugin now does, then run:
ayx_plugin_cli test This runs pytest backend. A freshly generated, unmodified plugin passes its own tests, so a failure after your edit points at the edit.
Install into Designer
For fast iteration, build and install in one step:
ayx_plugin_cli designer-install --install-type userRestart Designer. The plugin appears in the tool palette under your tool category. Place it on a workflow, connect an input, and run.
To produce a shareable package instead:
ayx_plugin_cli create-yxi The YXI is written to build/yxi/. Double-click it, or drag it into Designer, to install. Go to Package and Install.
Change Metadata Later
Help link:
ayx_plugin_cli update-tool-help --help-url https://example.com/helpAnything else in
ayx_workspace.json: Edit the file, then runayx_plugin_cli generate-config-filesand restart Designer. To learn which fields are safe to change, go to Workspace and Plugin Structure.
Next Steps
For details on CLI commands and their flags, go to Command Reference.
For information about what each generated file does, go to Workspace and Plugin Structure.