module

Manage and execute WASM modules, including Surrealism plugin modules: scaffold a project, build it, inspect the result, and run its functions from the command line.

Available since: v3.0.0

Note

Before you start - make sure you’ve installed SurrealDB.

Usage

surreal module [OPTIONS] <COMMAND>

Subcommand	Purpose
`surreal module init`	Initialise a new Surrealism module project.
`surreal module build`	Build a WASM module.
`surreal module run`	Run a function with arguments.
`surreal module sig`	Show the function signature.
`surreal module info`	Show the module information.
`surreal module help`	Print this message or the help of the given subcommand.

surreal module init

Scaffold a new Surrealism module project (Rust crate, surrealism.toml, .cargo/Config.toml, and starter src/lib.rs).

Usage

surreal module init [OPTIONS] [PATH]

Arguments

Name	Description
`[PATH]`	Directory to scaffold the crate in. The current directory is used when omitted.

Options

Name	Description
`--headless`	Scaffold without prompting, for use in scripts and CI.
`--org<ORG>`	Organisation the module belongs to.
`--name<NAME>`	Name of the module.

surreal module init

surreal module init writes the WASI build flags Surrealism needs into .cargo/config.toml. surreal module build applies the same flags when it invokes Cargo, so existing projects pick them up even if the file was not scaffolded yet.

.cargo/Config.toml flags

[build]
rustflags = ["--cfg", "tokio_unstable"]

For scripts or CI, use non-interactive mode:

surreal module init --headless --org surrealdb --name my_module ./path/to/crate

surreal module build

Build a WASM binary from the Rust source code. A binary must have the .surli file extension.

Usage

surreal module build [OPTIONS] [PATH]

Arguments

Name	Description
`[PATH]`	Path to the crate to build. The current directory is used when omitted.

Options

Name	Description
`-o<FILE>`	Path of the `.surli` binary to write.
`--debug`	Skip the usual optimisation pass for a faster build time in exchange for lower performance.

surreal module build -o demo.surli ../demo

Using --debug skips the usual optimisation pass for a faster build time in exchange for lower performance. Recommended when iterating and testing before producing a final build.

surreal module build --debug -o demo-debug.surli .

surreal module run

Run a single function from a compiled module, including functions that require arguments to be passed in.

Usage

surreal module run [OPTIONS] --fnc <FUNCTION> <FILE>

Arguments

Name	Description
`<FILE>` required	Path to the compiled `.surli` module.

Options

Name	Description
`--fnc<FUNCTION>` required	Name of the function to run.
`--arg<ARG>`	Value passed to the function. Functions that take no arguments need no `--arg`.

surreal module run --fnc can_drive --arg 17    demo.surli
surreal module run --fnc can_drive --arg 18    demo.surli
surreal module run --fnc result    --arg false demo.surli
surreal module run --fnc result    --arg true  demo.surli
surreal module run --fnc test_kv               demo.surli
surreal module run --fnc test_io               demo.surli
surreal module run --fnc test_none_value       demo.surli

surreal module sig

Show the signature for a single function in a compiled module.

Usage

surreal module sig [OPTIONS] --fnc <FUNCTION> <FILE>

Arguments

Name	Description
`<FILE>` required	Path to the compiled `.surli` module.

Options

Name	Description
`--fnc<FUNCTION>` required	Name of the function whose signature is shown.

surreal module sig --fnc can_drive demo.surli

surreal module info

Show the information held by a compiled WASM binary.

Usage

surreal module info [OPTIONS] <FILE>

Arguments

Name	Description
`<FILE>` required	Path to the compiled `.surli` module.

surreal module info demo.surli

Command help

To see the help information and usage instructions, in a terminal run the surreal module --help command without any further arguments. This output lists subcommands, global options, and shared logging flags for the module command.

surreal module --help

The output of the above command:

Manage and execute WASM modules

Usage: surreal module [OPTIONS] <COMMAND>

Commands:
  init   Initialize a new Surrealism module project
  run    Run a function with arguments
  sig    Show the function signature
  info   Show the module information
  build  Build a WASM module
  help   Print this message or the help of the given subcommand(s)

Options:
  -h, --help  Print help

Logging:
  -l, --log <LOG>                              The logging level for the command-line tool [env: SURREAL_LOG=] [default: info] [possible values: none, full, error, warn, info, debug, trace]
      --log-format <LOG_FORMAT>                The format for terminal log output [env: SURREAL_LOG_FORMAT=] [default: text] [possible values: text, json]
      --log-socket <LOG_SOCKET>                Send logs to the specified host:port [env: SURREAL_LOG_SOCKET=]
      --log-file-level <LOG_FILE_LEVEL>        Override the logging level for file output [env: SURREAL_LOG_FILE_LEVEL=] [possible values: none, full, error, warn, info, debug, trace]
      --log-otel-level <LOG_OTEL_LEVEL>        Override the logging level for OpenTelemetry output [env: SURREAL_LOG_OTEL_LEVEL=] [possible values: none, full, error, warn, info, debug, trace]
      --log-socket-level <LOG_SOCKET_LEVEL>    Override the logging level for unix socket output [env: SURREAL_LOG_SOCKET_LEVEL=] [possible values: none, full, error, warn, info, debug, trace]
      --log-socket-format <LOG_SOCKET_FORMAT>  The format for socket output [env: SURREAL_LOG_SOCKET_FORMAT=] [default: text] [possible values: text, json]
      --log-file-enabled                       Whether to enable log file output [env: SURREAL_LOG_FILE_ENABLED=]
      --log-file-path <LOG_FILE_PATH>          The directory where log files will be stored [env: SURREAL_LOG_FILE_PATH=] [default: logs]
      --log-file-name <LOG_FILE_NAME>          The name of the log file [env: SURREAL_LOG_FILE_NAME=] [default: surrealdb.log]
      --log-file-format <LOG_FILE_FORMAT>      The format for log file output [env: SURREAL_LOG_FILE_FORMAT=] [default: text] [possible values: text, json]
      --log-file-rotation <LOG_FILE_ROTATION>  The log file rotation interval [env: SURREAL_LOG_FILE_ROTATION=] [default: daily] [possible values: daily, hourly, never]

surreal module init

surreal module build

surreal module run

surreal module sig

surreal module info

Command help

Further reading