XTP CLI

The xtp CLI offers a variety of essential functions that support the entire plugin development and distribution lifecycle. The CLI lets developers:

Create: Generate boilerplate & compile plugin code. Idiomatic code generation is powered by the details set in a Host App's XTP Schema.
Test: Leverage a powerful testing and simulation system to verify that plugins function correctly and meet all requirements.
Push: Uploading the plugin to the platform for validation, hosting, distribution, download & execution.
Manage: Control the version and activation of plugins' installation in a Host App. Inspect authorized plugins' details, configurations, and status.

While the CLI is mostly targeted to plugin developers, we highly recommend Host App operators install it as well.

Installation

curl https://static.dylibso.com/cli/install.sh -s | bash

To verify that the installation worked correctly, run xtp in your terminal. You should see something like the following:

$ xtp

            d8P
         d888888P
?88,  88P  ?88'  ?88,.d88b,
 '?8bd8P'  88P   '?88'  ?88
 d8P?8b,   88b     88b  d8P
d8P' '?8b  '?8b    888888P'
                   88P'
                  d88
                  ?8P

Usage:
  xtp [command]

Available Commands:
  app             Manage your apps
  auth            Manage authentication status
  completion      Generate the autocompletion script for the specified shell
  extension-point Manage extensionpoints
  help            Help about any command
  login           log in
  plugin          Manage plugins
  self            Manage the CLI itself

Flags:
  -h, --help      help for xtp
  -v, --version   version for xtp

Use "xtp [command] --help" for more information about a command.

If you don't, there may be an issue with your $PATH environment variable. Reach out to us on Discord for help!

Usage

Create Plugins

Initializing a new plugin project through the CLI offers a streamlined & optimized developer experience. XTP enables generating common boilerplate code for serialization, function signatures, and more. This is all derived from the XTP Schema.

To generate a plugin starter project (highly recommended), run the xtp plugin init command:

Generate boilerplate code for the specified extension point

Usage:
  xtp plugin init --language [LANGUAGE] --path [PATH] --extension-point [Extension Point ID] --feature-flags [FEATURE_FLAGS] --template [TEMPLATE] [flags]

Flags:
  -a, --app string               The app ID the plugin is installed in
  -e, --extension-point string   The extension point ID to generate code for. Can't be used with --schema-file
  -f, --feature none             Feature flags to enable for the plugin. Pass in none to disable all feature flags.
  -h, --help                     help for init
  -l, --language string          The language to generate code in
  -p, --path string              The path to generate the code in
      --schema-file string       The schema file to generate code from. Can't be used with --extension-point
  -t, --template string          The template to use for code generation. Example: ./xtp-typescript-bindgen, @dylibso/xtp-typescript-bindgen, or https://github.com/dylibso/xtp-typescript-bindgen
  -y, --yes                      Skip confirmation prompt

If the command exits successfully, you will have a full plugin project generated at the path specified.

In addition to the boilerplate generated code, there is an xtp.toml file in the root of the output project directory. This file enables the rest of the xtp CLI experience to test, upload & bind plugins into Host Apps. You can edit it as you wish, but be aware of changes as they may impact the behavior of other xtp CLI actions.

A functional, but not exhaustive TOML configuration would look like:

app_id = "app_01j0ss4f9jea0sajj6njngrm8d"
bin = "dist/plugin.wasm"
extension_point_id = "ext_01j0t0wtzgfe1ttqr96d1z12yd"
name = "example-2" 

[scripts]
build = "npm run build"

[[test]]
# see the section on XTP Test & Simulations:
# https://docs.xtp.dylibso.com/...

note

By default, the name property in the xtp.toml file is set to the name of the directory you create when you run the xtp plugin init command. However, you can change name to anything you prefer by editing the file.

Test Plugins & Simulate Host Environments Locally

Testing the behavior and performance characteristics of a plugin is a critical step to the plugin lifecycle. Integrating dynamic, potentially untrusted code and executing it at runtime is complicated! Tests provide a level of assurance that every Host App needs in order to build reliable & stable plugin integrations.

Luckily, this is easy with XTP. Host Apps and plugin authors can write tests the many XTP Test libraries provided:

You can define tests to execute in your xtp.toml file using [[test]] sections. Read more here to better understand the configuration to run tests using the CLI.

Simulations

Just as you're able to write tests to validate plugin behavior locally, host users are able to provide tests that ensure plugin behavior meets expectations. These host-provided tests and mocks are called "Simulations". Whenever you push your plugin, XTP runs Simulations to validate it. You'll see the output of the simulation whenever you run xtp plugin push. (For the host's perspective on Simulations, see "Create Simulations"!) Whenever you push your plugin, you'll see output from simulation runs:

→ xtp plugin push
✅ Version ver_01j2ezfc4keedv36p5twwk4dj6 uploaded for Plugin plugin
🧪 validated content-type...!
🧪 validated artifact content as webassembly...!
🧪 validated checkfile in modsurfer
🧪 artifact is valid (great job!)
🧪 running simulations
🧪 Simulations
───────────────────────────────────────────────────────────────────────────────
       Simulation           Test Name            Info
───────────────────────────────────────────────────────────────────────────────
 ⏩    frobnicator                               skipped (binding is inactive)
 🧪    reticulates-splines  reticulates-splines
 ✅    reticulates-splines  reticulates-splines  all tests passed
 ✅    All simulations                           2 / 2 passed
✅ Version ver_01j2ezfc4keedv36p5twwk4dj6 has been processed for Plugin plugin

XTP will reject plugins which fail to pass tests under Simulation:

→ xtp plugin push
✅ Version ver_01j2ezv4mtfqn9bdmfc1gzkq5w uploaded for Plugin plugin-chris
🧪 validated content-type...!
🧪 validated artifact content as webassembly...!
🧪 validated checkfile in modsurfer
🧪 artifact is valid (great job!)
🧪 running simulations
🧪 Simulations summary
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
       Simulation           Test Name            Info
───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
 ❌    frobnicator          frobnicator          Uncaught TypeError: not a function    at assert (script.js:125)    at test (script.js:169)
 🧪    reticulates-splines  reticulates-splines
 ✅    reticulates-splines  reticulates-splines  all tests passed
 ❌    All simulations                           0 / 1 (1 failure)
Error: processing Plugin failed: ERROR

In this case, xtp plugin push will display the error output in order to debug the failure.

Deploy Your Plugin

The XTP CLI allows you, as a plugin author, to compile and push plugin code to host applications in a convenient and optimized way. It's as easy as running xtp plugin push.

As a plugin author, you get to choose a name for your plugin, configured in xtp.toml. By default, this will be the directory name where you created your plugin. When you xtp plugin push your code, the latest version of your plugin will be made available to the host under that name. (We call this "binding" a plugin.)

(Advanced users might want to advertise a plugin to the host under a different name than the plugin name. XTP supports this use case via xtp plugin push --as <name> and the xtp bind subcommand. See the section on Artifacts and Bindings for more information.)

Plugins are validated by common tests built-in to XTP, as well as host-provided Simulations before activation.

Deactivate a Plugin

You can deactivate or "unbind" a plugin from an Extension Point by running xtp plugin unbind --name <name>, using the name of the plugin as defined in the name property of the xtp.toml, or the name passed in via --as parameter specified when the plugin was uploaded.

Inspecting & Exploring Plugins

The CLI provides simple plugin catalog inspection and exploration. Guest users can list their plugins per Extension Points and access information about them.

Use xtp plugin view and xtp plugin list to interactively navigate and explore your plugins applicable to the Host Apps and Extension Points you have access to.

Installation​

Usage​

Create Plugins​

Test Plugins & Simulate Host Environments Locally​

Simulations​

Deploy Your Plugin​

Deactivate a Plugin​

Inspecting & Exploring Plugins​