# module

A command used to compile, manage and execute Surrealism plugin modules.

_(since v3.0.0)_

> [!NOTE: BEFORE YOU START]
> Make sure you’ve [installed SurrealDB](/docs/running/installation.md) — it should only take a second!

## Commands and examples

The `surreal module build` command is used to build a WASM binary from the Rust source code. A binary must have the `.surli` file extension.

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

The `surreal module info` command can then be used to see the information about a compiled WASM binary.

```bash
surreal module info demo.surli
```

Individual functions can be run on the command line with the `surreal module run` command, including functions that require arguments to be passed in. Here are a number of examples.

```bash
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
```

The `surreal module sig` command can be used to see the the signature for a function.

```bash
surreal module sig --fnc can_drive demo.surli
```

## `surreal module init`

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

```bash
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.

```toml title=".cargo/Config.toml flags"
[build]
rustflags = ["--cfg", "tokio_unstable"]
```

For scripts or CI, use non-interactive mode:

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

## `surreal module build --debug`

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.

```bash
surreal module build --debug -o demo-debug.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.

```bash
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]
```

## Further reading

- [Surrealism extensions overview](/docs/learn/extensions/plugins/overview.md) — end-to-end workflow
- [Creating custom modules](/docs/learn/extensions/guides/creating-custom-modules.md) — attributes, `surrealism.toml`, and attached filesystems