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

# Working with extensions

Scaffold, build, inspect, run, sign and install Surrealism WebAssembly extensions from the command line with surreal ext, the extension component of the Surreal CLI.

Extensions are WebAssembly packages that add functions to the database. This page shows the command-line workflow for a [Surrealism](/docs/learn/extensions/plugins/overview.md) extension: scaffold a project, build it, inspect the result, run a function, then sign and install it. Extensions were called modules before SurrealDB 4.0, when the commands below were `surreal db module` commands, part of the database.

The commands belong to `ext`, the extension component of the Surreal CLI, run as `surreal ext`. Its first release is not published yet, so `surreal install ext` does not work today.

## Create a project

```bash
surreal ext init my-extension
```

`init` scaffolds a Rust project with a `package.toml` and a starter `src/lib.rs`. It asks for the organisation and extension name interactively. In a script, add `--headless` with `--org`, and `--name` when the extension should not take the folder's name.

```bash
surreal ext init my-extension --headless --org acme --name my-extension
```

## Build the extension

Run `build` from the project folder, or name the source folder. The archive is named after the organisation, name and version in `package.toml` unless `--out` names it.

```bash
surreal ext build
surreal ext build ./my-extension --out my-extension.surli
```

A build is a release build. Add `--debug` for a debug build.

## Inspect and run it

`info` lists the functions the archive exports, and `sig` shows the signature of one of them.

```bash
surreal ext info my-extension.surli
surreal ext sig --fnc greet my-extension.surli
```

`run` calls a function with arguments, without a database. Repeat `--arg` for each argument, written as a SurrealQL value.

```bash
surreal ext run --fnc greet --arg '"World"' my-extension.surli
```

## Sign and install it

To let others check where an archive came from, name a signer in `package.toml`, build again, and sign the archive:

```bash
surreal ext config signer ssh ~/.ssh/release.pub
surreal ext build --out my-extension.surli
surreal ext sign --key ~/.ssh/release my-extension.surli
```

Place the archive in a [bucket](/docs/reference/query-language/statements/define/bucket.md) of the database, then install it. `install` shows the signer, the digest and the capabilities the extension requests, asks which to accept, and defines it:

```bash
surreal ext install 'f"extensions:/my-extension.surli"' --as greeting \
    -e ws://localhost:8000 -u root -p secret --ns app --db main
```

The extension's functions are then called from SurrealQL as `ext::greeting::greet('World')`. [`DEFINE EXTENSION`](/docs/reference/query-language/statements/define/extension.md) defines an extension directly, and the [Surrealism guides](/docs/learn/extensions/plugins/overview.md) cover writing the functions and the attribute reference.

## Reference

The command reference is [`surreal ext`](/docs/reference/cli/ext.md).