Skip to main content

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

sdk-workspace-init

Turn the current folder into a workspace.

No

create-ayx-plugin

Add a plugin to the workspace.

Yes

update-tool-help

Set the help URL for one or all plugins.

Yes

generate-ui

Create or refresh configuration panel scaffolding.

Yes

generate-tests

Create or refresh test scaffolding.

Yes

generate-config-files

Regenerate Designer configuration files.

Yes

create-yxi

Build an installable package.

Yes, with at least one plugin.

designer-install

Build and install into Designer.

Yes, with at least one plugin.

install-yxi

Install an existing package.

No

test

Run the workspace’s tests.

Yes

version

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 python

Option

Required

Type

Default

Meaning

--package-name

Yes

String

None

Package name. Also the name of the YXI that is built. Use an alphanumeric string.

--tool-category

No

String

Python SDK Examples

Designer tool palette tab where the plugins appear. Designer creates the tab if it does not exist.

--description

No

String

Empty

Package description. Shown to users when they install the YXI.

--author

No

String

Empty

Author recorded in the metadata.

--company

No

String

Empty

Company recorded in the metadata.

--backend-language

Yes

String

None

Back-end language. python is the only supported value.

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-output

Option

Required

Default

Meaning

--tool-name

Yes

None

Plugin display name. The class name and file names derive from it. Refer to the name rules below.

--tool-type

No

single-input-single-output

Template shape. Refer to the table below.

--writes-output-data / --no-writes-output-data

No

false

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.

--description

No

Empty

Text a user sees when selecting the plugin in the Designer tool palette.

--tool-version

No

1.0

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.

--dcm-namespace

No

Empty

Namespace for Data Connection Manager (DCM) schema registration. Leave empty if the plugin does not use DCM.

--tool-category

No

inherits package

Tool palette tab for this plugin only. Flag only. There is no prompt.

--omit-ui / --no-omit-ui

No

false

Skip or force configuration panel generation. Without --omit-ui, Node and npm must be installed.

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

--tool-type

Shape

input

No input anchors. Generates data.

output

Input anchor only. Consumes data.

single-input-single-output

One input, one output.

multiple-inputs

Several input anchors.

multiple-outputs

Several output anchors.

optional

An input anchor that may be unconnected.

multi-connection-input-anchor

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 is ATestPlugin.

  • 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__.py

  • Default 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:

  1. Remove the plugin’s entry from the tools key of ayx_workspace.json.

  2. Remove configuration/<Class>_<version>/.

  3. Remove backend/ayx_plugins/<snake_name>.py.

  4. Remove the import for the plugin from backend/ayx_plugins/__init__.py.

  5. Remove ui/<Class>/ if it was created. You may need to force-remove it.

  6. Remove backend/tests/test_<snake_name>.py if 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-yxi

Option

Required

Meaning

--help-url

Yes

The new help page URL.

--tool-name

No

Limit the update to one plugin. If omitted, every plugin is updated.

--build-yxi

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 MyFirstPlugin

Option

Meaning

--tool-name

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-failures

Option

Default

Meaning

--tool-name

All Plugins

Plugin to generate for. Can be repeated.

--warn-possible-failures / --no-warn-possible-failures

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-yxi

Option

Default

Meaning

--omit-ui

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 user

Option

Default

Meaning

--install-type

user

user installs to %APPDATA%\Alteryx\Tools for the current user. admin installs to %ALLUSERSPROFILE%\Alteryx\Tools for all users and requires admin access

--omit-ui

Off

Build without configuration panels.

--dev

Off

Development install. Does not bundle dependencies and deletes build/ after installing. For more information, go to Packaging and Installing.

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 user

Option

Required

Default

Meaning

--yxi-path

Yes

None

Path to the YXI. The file must exist and be readable.

--install-type

No

user

user or admin. Admin installs require admin access.

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 test

Run 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