CLI Command Reference
This page explains every ayx_plugin_cli command, with its flags, defaults, and behavior. Run ayx_plugin_cli <command> --help for the text of your installed version.
Summary
Command | Purpose | Needs a Workspace |
|---|---|---|
| Turn the current folder into a workspace. | No |
| Add a plugin to the workspace. | Yes |
| Set the help URL for one or all plugins. | Yes |
| Create or refresh configuration panel scaffolding. | Yes |
| Create or refresh test scaffolding. | Yes |
| Regenerate Designer configuration files. | Yes |
| Build an installable package. | Yes, with at least one plugin. |
| Build and install into Designer. | Yes, with at least one plugin. |
| Install an existing package. | No |
| Run the workspace’s tests. | Yes |
| Print the CLI version. | No |
Common Behavior
Prompts. An option you do not pass on the command line is prompted for interactively, where a prompt exists.
Workspace required. Commands that need a workspace stop with an "ayx_workspace.json not found" error when run outside one. Run them from the workspace root.
Errors. Errors print as
ERROR: <message>and the command exits with code 1. Validation failures stop the command before it changes anything.Update check. On start, the CLI checks for a newer release and prints a warning if one is available. The command still runs.
Plugin names. Flags are named
--tool-name,--tool-type, and so on. These names are fixed even though the documentation says "plugin".
sdk-workspace-init
Creates a workspace in the current folder. It writes ayx_workspace.json, creates the backend/, configuration/, and DcmSchemas/ folders, adds a README, .gitignore, and pyproject.toml, and generates the top-level configuration. If any file or folder it creates already exists, it asks before overwriting it.
ayx_plugin_cli sdk-workspace-init --package-name DemoPackage --backend-language pythonOption | Required | Type | Default | Meaning |
|---|---|---|---|---|
| Yes | String | None | Package name. Also the name of the YXI that is built. Use an alphanumeric string. |
| No | String | | Designer tool palette tab where the plugins appear. Designer creates the tab if it does not exist. |
| No | String | Empty | Package description. Shown to users when they install the YXI. |
| No | String | Empty | Author recorded in the metadata. |
| No | String | Empty | Company recorded in the metadata. |
| Yes | String | None | Back-end language. |
The copyright year is set to the current year, the Python version to that of the interpreter that ran the command, and the default plugin version to 1.0.
create-ayx-plugin
Adds a plugin. It generates the backend module, tests, configuration files, and (unless skipped) the configuration panel, and registers the plugin in ayx_workspace.json. It rejects a name that duplicates an existing class or file name.
ayx_plugin_cli create-ayx-plugin --tool-name MyFirstPlugin --tool-type single-input-single-outputOption | Required | Default | Meaning |
|---|---|---|---|
| Yes | None | Plugin display name. The class name and file names derive from it. Refer to the name rules below. |
| No | | Template shape. Refer to the table below. |
| No | | Mark a plugin that writes to files, databases, or services, so Designer’s Disable All Tools that Write Output option in Workflow Configuration Runtime settings can disable it. Answer yes for output-style plugins that send data elsewhere. |
| No | Empty | Text a user sees when selecting the plugin in the Designer tool palette. |
| No |
| Plugin version. Part of the generated folder name. Lets you keep several versions of a plugin so users can upgrade or stay on an earlier one. |
| No | Empty | Namespace for Data Connection Manager (DCM) schema registration. Leave empty if the plugin does not use DCM. |
| No | inherits package | Tool palette tab for this plugin only. Flag only. There is no prompt. |
| No | | Skip or force configuration panel generation. Without |
Prompts appear in this order for any option you do not pass: Tool Name, Tool Type, writes output data, Description, Tool Version, namespace, and skip UI.
Plugin Types
| Shape |
|---|---|
| No input anchors. Generates data. |
| Input anchor only. Consumes data. |
| One input, one output. |
| Several input anchors. |
| Several output anchors. |
| An input anchor that may be unconnected. |
| One input anchor that accepts several connections. |
Name Rules
The name must start with a letter and contain only letters, digits, and spaces.
Spaces are removed, and the name is converted to Pascal case for the class, UI, and configuration names. For "A Test Plugin", the file is
a_test_plugin.py, and the class isATestPlugin.A name that would produce a file or configuration that already exists in the workspace is rejected.
What It Generates
The plugin’s Python module and its entry in
backend/ayx_plugins/__init__.pyDefault test file in
backend/tests/.Configuration files in
configuration/<Class>_<version>/.Configuration panel in
ui/<Class>/, unless skipped.Updates to
ayx_workspace.json.
Unattended Runs
Pass every option as a flag. Use --no-omit-ui when you need the panel, and send an empty line on standard input for the namespace prompt if you do not pass --dcm-namespace.
If the Command Fails Partway
The workspace file is updated before the scaffolding runs, so a failure can leave half-finished files. To clean up, follow these steps:
Remove the plugin’s entry from the
toolskey ofayx_workspace.json.Remove
configuration/<Class>_<version>/.Remove
backend/ayx_plugins/<snake_name>.py.Remove the import for the plugin from
backend/ayx_plugins/__init__.py.Remove
ui/<Class>/if it was created. You may need to force-remove it.Remove
backend/tests/test_<snake_name>.pyif it was created.
update-tool-help
Sets the help URL stored for one plugin or for every plugin in the workspace.
ayx_plugin_cli update-tool-help --help-url https://example.com/help
ayx_plugin_cli update-tool-help --help-url https://example.com/help --tool-name MyFirstPlugin --build-yxiOption | Required | Meaning |
|---|---|---|
| Yes | The new help page URL. |
| No | Limit the update to one plugin. If omitted, every plugin is updated. |
| No | Build a YXI after updating (default: off). |
This command changes only ayx_workspace.json. Run generate-config-files after to refresh the generated XML, unless you use --build-yxi.
generate-ui
Creates or refreshes the configuration panel scaffold. Requires Node and npm.
ayx_plugin_cli generate-ui
ayx_plugin_cli generate-ui --tool-name MyFirstPluginOption | Meaning |
|---|---|
| Plugin to generate for. Can be repeated. If omitted, runs for all plugins. |
Use it when the frontend template changes, or to regenerate the scaffold for an existing plugin.
generate-tests
Creates or refreshes the default test file for one or more plugins at backend/tests/test_<snake_name>.py.
ayx_plugin_cli generate-tests
ayx_plugin_cli generate-tests --tool-name MyFirstPlugin --no-warn-possible-failuresOption | Default | Meaning |
|---|---|---|
| All Plugins | Plugin to generate for. Can be repeated. |
| On | Print a reminder that generated tests usually need manual edits. |
Regenerating overwrites the file. Keep hand-written tests in separate files.
generate-config-files
Regenerates configuration/Config.xml, each plugin’s configuration XML, and each plugin’s manifest.json from ayx_workspace.json. It takes no options.
ayx_plugin_cli generate-config-files Run it after you hand-edit ayx_workspace.json or run update-tool-help.
create-yxi
Builds a YXI, the package format Designer installs, from the whole workspace. The result is build/yxi/<package>.yxi. The workspace needs at least one plugin.
ayx_plugin_cli create-yxiOption | Default | Meaning |
|---|---|---|
| Off | Leave configuration panels out of the package. Use only for plugins without a panel. |
To install the YXI, double-click it or drag it into Designer, or use install-yxi.
designer-install
Builds the YXI from the current workspace and installs it into Designer. This is the most direct route from workspace code to a working plugin in Designer.
ayx_plugin_cli designer-install --install-type userOption | Default | Meaning |
|---|---|---|
| | |
| Off | Build without configuration panels. |
| Off | Development install. Does not bundle dependencies and deletes |
If a plugin with the same name is already installed, the CLI asks before overwriting it. Restart Designer after the first install and after any change to ayx_workspace.json.
install-yxi
Installs an existing YXI into Designer.
ayx_plugin_cli install-yxi --yxi-path path\to\package.yxi --install-type userOption | Required | Default | Meaning |
|---|---|---|---|
| Yes | None | Path to the YXI. The file must exist and be readable. |
| No | | |
The command asks before overwriting an installed plugin of the same name. It does not support YXIs built with the original, pre-CLI Alteryx Python SDK.
test
Runs the workspace’s tests. For a Python workspace, this runs pytest backend.
ayx_plugin_cli testRun it after every meaningful change to the backend or the test data.
version
Prints the installed CLI version as Alteryx CLI Version: <version>.
ayx_plugin_cli version