Extism CLI

The extism CLI is a useful but optional tool for developing with Extism. It handles a few things such as installing the shared library (Extism Runtime), or invoking plug-ins from the command line.

The following instructions will walk you through how to install the Extism CLI, and then the installation of the shared library which a Host SDK will look for automatically.

Install the Extism CLI

curl -s https://get.extism.org/cli | sh

Or to a specific path:

curl -s https://get.extism.org/cli | sh -s -- -o $HOME/.local/bin

See the help output for more information:

curl -s https://get.extism.org/cli | sh -s -- -h

Releases are also available on Github: https://github.com/extism/cli/releases

Remove old installation If you have installed the old cli via python,

you may need to remove it:

pip3 uninstall extism_cli --break-system-packages
which extism # shouldn't print anything, if it does, delete it

In Containers (using Docker, etc)

To install Extism and the shared library in a container, use this in the same stage your app runs in:

RUN curl -s https://get.extism.org/cli | sh -s -- -y
RUN extism lib install
ENV LD_LIBRARY_PATH="/usr/local/lib:$LD_LIBRARY_PATH" 

If you need to keep your final stage more minimal than curl or the extism tool can run in, you can run those commands in a build stage, and in your final stage do:

ENV LD_LIBRARY_PATH="/usr/local/lib:$LD_LIBRARY_PATH" 
COPY --from=build /usr/local/include/extism.h /usr/local/include/extism.h
COPY --from=build /usr/local/lib/libextism.so /usr/local/lib/libextism.so
COPY --from=build /usr/local/lib/libextism.a /usr/local/lib/libextism.a
COPY --from=build /usr/local/lib/pkgconfig/extism.pc /usr/local/lib/pkgconfig/extism.pc
COPY --from=build /usr/local/lib/pkgconfig/extism-static.pc /usr/local/lib/pkgconfig/extism-static.pc

Using the Extism CLI

The most common use-case is to to install Extism from Github releases, and then install the library and header file into the installation prefix of your choice. The default prefix is /usr/local, so libraries will be installed to /usr/local/lib and the header will be installed to /usr/local/include.

Some language SDKs come bundled with the runtime and some need you to

install the runtime separately. If your language needs you to install the runtime, the SDKs readme will say so in the install instructions. :::

sudo extism lib install

tell sudo to use the PATH defined for your user with: sudo -E env "PATH=$PATH" extism lib install :::

Installing the latest from git

It's also possible to install the latest build from the main git branch:

sudo extism lib install --version git

Overriding install location

Pass the --prefix argument a path on disk where extism CLI will install the system files:

extism lib install --prefix ~/.local

Generating Plugin PDK Starters

You can use the Extism CLI to quickly start a new plugin project:

extism generate plugin -o new-plugin
Select a PDK language to use for your plugin:  
                                                
> 1. Rust                                      
JavaScript                                
Go                                        
Zig                                       
C#                                        
F#                                        
C                                         
Haskell                                   
AssemblyScript

Other CLI Features

Usage:
  extism [command]

Available Commands:
  call        Call a plugin function
  completion  Generate the autocompletion script for the specified shell
  help        Help about any command
  lib         Manage libextism

Flags:
      --github-token string   Github access token, can also be set using the $GITHUB_TOKEN env variable
  -h, --help                  help for extism
  -q, --quiet                 Enable additional logging
  -v, --verbose               Enable additional logging
      --version               version for extism

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

Call plug-in functions

You can use the extism CLI as a test runner to check your plug-ins outside of any Host program:

extism call --input "this is a test" test/code.wasm count_vowels
{"count": 4}

For plugins which require manifest and configuration properties to be set, you can pass these as flags to the call command.

Use extism help call to explore the available flags:

Usage:
  extism call [flags] wasm_file function

Flags:
      --allow-host stringArray                  Allow access to an HTTP host, if no hosts are listed then all requests will fail. Globs may be used for wildcards
      --allow-path stringArray                  Allow a path to be accessed from inside the Wasm sandbox, a path can be either a plain path or a map from HOST_PATH:GUEST_PATH
      --config stringArray                      Set config values, should be in KEY=VALUE format
  -h, --help                                    help for call
      --http-response-max extism_http_request   Maximum HTTP response size in bytes when using extism_http_request (default -1)
  -i, --input string                            Input data
      --link stringArray                        Additional modules to link
      --log-level string                        Set log level: trace, debug, warn, info, error
      --loop int                                Number of times to call the function (default 1)
  -m, --manifest                                When set the input file will be parsed as a JSON encoded Extism manifest instead of a WASM file
      --memory-max int                          Maximum number of pages to allocate
      --set-config config                       Create config object using JSON, this will be merged with any config arguments
      --stdin                                   Read input from stdin
      --timeout uint                            Timeout in milliseconds
      --var-max int                             Maximum size in bytes of Extism var store (default -1)
      --wasi                                    Enable WASI

Global Flags:
      --github-token string   Github access token, can also be set using the $GITHUB_TOKEN env variable
  -q, --quiet                 Suppress output
  -v, --verbose               Enable additional logging

Check installed version

The CLI can also be used to get information about the installed version of libextism:

extism lib check
v0.5.0

Install the Extism CLI​

In Containers (using Docker, etc)​

Using the Extism CLI​

Installing the latest from git​

Overriding install location​

Generating Plugin PDK Starters​

Other CLI Features​

Call plug-in functions​

Check installed version​