> Full SurrealDB documentation index: https://surrealdb.com/docs/llms.txt

# module

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

_(since v3.0.0)_

Manage and execute WASM modules, including [Surrealism](/docs/learn/extensions/plugins/overview.md) plugin modules: scaffold a project, build it, inspect the result, and run its functions from the command line, using the [installed](/docs/explore/cli/install.md) `surreal` CLI.

<Synopsis>
surreal db module [OPTIONS] <COMMAND>
</Synopsis>

> [!NOTE]
> A dedicated `mod` component of the launcher will supersede `surreal db module`. Until it is released, `surreal db module` is the way to work with modules from the command line. The top-level form, `surreal module`, is deprecated and prints a warning that names `surreal db module`.

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

## surreal db module init {#module-init}

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

<Synopsis>
surreal db module init [OPTIONS] [PATH]
</Synopsis>

<OptionsTable
    title="Arguments"
    options={[
        {
            "name": "[PATH]",
            "description": "Directory to scaffold the crate in. The current directory is used when omitted."
        }
    ]}
/>

<OptionsTable
    title="Options"
    options={[
        {
            "name": "--headless",
            "description": "Scaffold without prompting, for use in scripts and CI."
        },
        {
            "name": "--org",
            "value": "<ORG>",
            "description": "Organisation the module belongs to."
        },
        {
            "name": "--name",
            "value": "<NAME>",
            "description": "Name of the module."
        }
    ]}
/>

```bash
surreal db module init
```

`surreal db module init` writes the WASI build flags Surrealism needs into `.cargo/config.toml`. `surreal db 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 db module init --headless --org surrealdb --name my_module ./path/to/crate
```

## surreal db module build {#module-build}

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

<Synopsis>
surreal db module build [OPTIONS] [PATH]
</Synopsis>

<OptionsTable
    title="Arguments"
    options={[
        {
            "name": "[PATH]",
            "description": "Path to the crate to build. The current directory is used when omitted."
        }
    ]}
/>

<OptionsTable
    title="Options"
    options={[
        {
            "name": "-o",
            "value": "<FILE>",
            "description": "Path of the `.surli` binary to write."
        },
        {
            "name": "--debug",
            "description": "Skip the usual optimisation pass for a faster build time in exchange for lower performance."
        }
    ]}
/>

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

```bash
surreal db module build --debug -o demo-debug.surli .
```

## surreal db module run {#module-run}

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

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

<OptionsTable
    title="Arguments"
    options={[
        {
            "name": "<FILE>",
            "required": true,
            "description": "Path to the compiled `.surli` module."
        }
    ]}
/>

<OptionsTable
    title="Options"
    options={[
        {
            "name": "--fnc",
            "value": "<FUNCTION>",
            "required": true,
            "description": "Name of the function to run."
        },
        {
            "name": "--arg",
            "value": "<ARG>",
            "description": "Value passed to the function. Functions that take no arguments need no `--arg`."
        }
    ]}
/>

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

## surreal db module sig {#module-sig}

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

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

<OptionsTable
    title="Arguments"
    options={[
        {
            "name": "<FILE>",
            "required": true,
            "description": "Path to the compiled `.surli` module."
        }
    ]}
/>

<OptionsTable
    title="Options"
    options={[
        {
            "name": "--fnc",
            "value": "<FUNCTION>",
            "required": true,
            "description": "Name of the function whose signature is shown."
        }
    ]}
/>

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

## surreal db module info {#module-info}

Show the information held by a compiled WASM binary.

<Synopsis>
surreal db module info [OPTIONS] <FILE>
</Synopsis>

<OptionsTable
    title="Arguments"
    options={[
        {
            "name": "<FILE>",
            "required": true,
            "description": "Path to the compiled `.surli` module."
        }
    ]}
/>

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

## Command help

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

```bash
surreal db module --help
```

The output of the above command:

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