Workspace and Plugin Structure
This page explains how the CLI organizes a project: what a workspace and a plugin are, what the generated folders contain, and what ayx_workspace.json holds.
Workspace and Plugin
A workspace is the project root created by
ayx_plugin_cli sdk-workspace-init. It owns the metadata fileayx_workspace.json, the shared build configuration, and the list of plugins.A plugin is one Designer tool created inside the workspace with
create-ayx-plugin. It has a Python class, generated configuration files, generated tests, and optionally a configuration panel project.One workspace builds one distributable package (one YXI). That package can hold one plugin or several.
Situation | Structure |
|---|---|
One standalone plugin. | One workspace, one plugin. |
Several plugins released together with shared metadata. | One workspace, several plugins. |
Plugins with different release schedules or owners. | Separate workspaces. |
Generated Layout
After sdk-workspace-init and one create-ayx-plugin --tool-name MyFirstPlugin:
MyWorkspace/
ayx_workspace.json
pyproject.toml
README.md
.gitignore
backend/
requirements-local.txt
requirements-thirdparty.txt
setup.py
ayx_plugins/
__init__.py
my_first_plugin.py
tests/
README.md
test_my_first_plugin.py
configuration/
Config.xml
default_package_icon.png
MyFirstPlugin_1_0/
icon.png
manifest.json
MyFirstPlugin_1_0Config.xml
ui/ (only when a configuration panel was generated)
MyFirstPlugin/
DcmSchemas/ (used by plugins that register DCM schemas)
.ayx_cli.cache/ (build cache, created by CLI commands)
build/yxi/ (created by create-yxi)Initialization also creates a few additional empty folders for optional features. Leave them in place.
Path | Role | Edit by hand? |
|---|---|---|
| Workspace and plugin metadata. | Rarely. Refer to Editing the Workspace File. |
| The plugin’s Python class. | Yes. This is where behavior lives. |
| Imports each plugin class so the runtime can find it. | Rarely. |
| Generated pytest tests. | Yes. They need editing to match real behavior. |
| Third-party Python dependencies bundled into the package. | Yes. Add packages the plugin imports. |
| Local Python packages bundled into the package. | Yes, when the plugin depends on local code. |
| Packaging boilerplate for the backend. | Rarely |
| Package-level Designer configuration. | No. It is regenerated. |
| Per-plugin icon, manifest, and configuration XML. | No, except replacing |
| The plugin’s configuration panel project. | Yes |
| pytest settings ( | Rarely |
Plugin Naming
You can enter a plugin name with spaces, such as "A Test Plugin". The CLI derives the other names from it:
Item | Example for |
|---|---|
Class, UI, and Configuration Name | |
Python File | |
Configuration Folder | |
A plugin name must start with a letter and contain only letters, digits, and spaces. Names that would collide with an existing plugin’s class or file are rejected.
ayx_workspace.json
ayx_workspace.json is the source of truth for the workspace. It describes the set of plugins that will be packaged and distributed, and the CLI reads it to generate the top-level Config.xml, each plugin’s configuration XML and manifest, and the YXI. It is created when you initialize the workspace, and the CLI updates it as you add plugins so it stays in sync with the folder structure.
Package-Level Fields
Field | Meaning |
|---|---|
| Package name. Also the YXI file name. |
| Default Designer tool palette tab for every plugin. |
| Package icon ( |
| Package metadata. |
| CLI version that created the workspace. |
| |
| Python version for the packaged plugins. Must match the target Designer release. |
| Dependency files bundled into the package. |
| Default plugin version. |
Per-Plugin Fields (under tools.<Name>)
Field | Meaning |
|---|---|
| Where the class lives and its name. Drives generated file and folder names. |
| Display name in Designer. |
| Plugin description. |
| Plugin version. Part of the |
| Tool palette search tags. |
| Help link opened from Designer. Defaults to |
| Plugin icon, relative to the workspace. |
| Anchor names, labels, |
| Marks plugins that write to an external destination, so Designer’s option to Disable All Tools that Write Output in Workflow Configuration Runtime settings can disable them. |
| Data Connection Manager (DCM) schema namespace. Empty when the plugin does not use DCM. |
| Per-plugin palette override, |
Sample File
An illustrative file for a workspace with one plugin. Your values will differ.
{
"name": "TestTools",
"tool_category": "Test Tools",
"package_icon_path": "configuration\\default_package_icon.png",
"author": "John Doe",
"company": "Alteryx, Inc",
"copyright": "2026",
"description": "A sample Alteryx workspace",
"ayx_cli_version": "1.4.0",
"backend_language": "python",
"backend_language_settings": {
"python_version": "3.13",
"requirements_local_path": "backend\\requirements-local.txt",
"requirements_thirdparty_path": "backend\\requirements-thirdparty.txt"
},
"tools": {
"TestPlugin": {
"backend": {
"tool_module": "ayx_plugins",
"tool_class_name": "TestPlugin"
},
"ui": {},
"configuration": {
"long_name": "Test Plugin",
"description": "",
"version": "1.0",
"search_tags": [],
"help_url": "https://help.alteryx.com/developer-help",
"icon_path": "configuration\\TestPlugin_1_0\\icon.png",
"writes_output_data": false,
"tool_category": null,
"input_anchors": {
"Input": { "label": "", "allow_multiple": false, "optional": false }
},
"output_anchors": {
"Output": { "label": "", "allow_multiple": false, "optional": false }
}
}
}
},
"tool_version": "1.0"
}Editing the Workspace File
The CLI manages this file, so prefer CLI commands such as create-ayx-plugin and update-tool-help. If you edit it by hand:
Keep to metadata such as descriptions, search tags, help URL, and categories. Editing names, versions, or anchors renames generated folders and breaks references inside them. Recreate the plugin instead.
Run
ayx_plugin_cli generate-config-filesafterward.Restart Designer.
Hand edits can cause unpredictable results, so treat them as an advanced option.
Generated Configuration Files
configuration/Config.xmldescribes package metadata at the top level.Each plugin’s
<Class>_<version>Config.xmlis used by the plugin to get and set anchors.Each plugin’s
manifest.jsondescribes the plugin to Designer.
Do not edit these. generate-config-files rebuilds all of them from ayx_workspace.json, and create-ayx-plugin refreshes them when it adds a plugin. update-tool-help changes only ayx_workspace.json, so run generate-config-files after it.
Next Steps
For information on every CLI command, with its flags, defaults, and behavior, go to Command Reference.
To learn how to turn a workspace into something Designer can run, go to Package and Install.