relate extension

relate extension manages extensionsextension A package that adds an action to the CLI, run as relate run <name> and installed with relate extension install. Read more in the glossary: packages that add an action to the CLI, run as relate run <name>. It has five actions. init scaffolds a new package, check tests a package directory without installing it, install puts a package on the machine from one of four sources, list prints what is installed, and remove uninstalls one. Only install and list --available use the network; the other actions read and write local files, and none of them opens a storestore A relate database: a directory, a single .rl file, or :memory:, opened with --database. Read more in the glossary.

Synopsis

relate extension init <name> [--lang sh|py|ts|rust]
relate extension install <name> [--github REPO@TAG|@SHA] [--url URL] [--from DIR] [--version V] [--force] [--re-approve | --approve SHA]
relate extension list [--available | --trust]
relate extension remove <name> [--forget-pin]
relate extension check <dir>

Options

Each flag belongs to one action, named in its row; a flag given to another action is a usage error. Of the install sources, --github, --url and --from name where the package comes from, and two of them together are a usage error; with none, the source is the first-party channel.

Where packages live

When XDG_CONFIG_HOME is unset, empty or a relative path, ~/.config takes its place. This directory is the only place relate looks for extensions: never the working directory, so a cloned repository cannot add an action to the CLI.

The manifest, extension.json, declares the package: kind (command), name (the action's name after relate run), version, protocol (the Model Context Protocol revision it speaks, 2025-06-18), the flags table, commit (per-batch or whole-import) and executable, a path inside the package directory, and the optional positional, requires-fresh-store and hidden. The relate run reference covers the flags table, and Write an extension the rest.

init

relate extension init <name> creates ./<name>/ with three items (four for --lang rust) and prints them, with the two commands that install and run the package:

The sh, py and ts executables hold a generated protocol client inline, so they depend on no client library; the Rust project depends on the relate-wire crate instead. Each has a walk() function to edit. The sample writes one :Scaffold node and reports a greeting built from --name. An existing directory of that name is refused (exit code 1); a name with a path separator, a reserved command word as the name, or an unknown --lang is a usage error (exit code 2).

check

relate extension check <dir> runs the package through six stages, in the order a mount uses them, printing one line per stage and stopping at the first failure:

A package that passes every stage gets a seventh line about its GitHub pin (pin: approved, pin: drifted, pin: not from a GitHub source (<tier>) or pin: unknown), which never changes the exit code. check opens no store, installs nothing and fetches nothing, but the spawn stage starts the package's executable, so any code the package runs when it starts runs with the user's permissions; it is not a sandbox. Each stage waits at most ten seconds. It exits 0 when the package would mount.

install

relate extension install <name> takes the package from one source. The source is the trust decision, and the marker records it as the package's tier:

Every tier then runs the same package rules (the manifest decodes, the executable stays inside the package, the protocol matches, the name collides with no command and no installed extension) in a staging directory beside the destination, writes the marker, and renames the package into place. A failed install leaves nothing behind. On success it prints one line naming the tier, the name, the version and the source, such as installed local extension team-import 0.1.0 from ./team-import.

The extension install guide walks through each tier, and the security reference covers the signing key.

list

--available and --trust together are a usage error.

remove

relate extension remove <name> deletes the package directory and prints removed extension <name> (<path>). It requires the provenance marker: a directory without one, such as a package copied by hand, is refused with a message naming the path, and remove has no --force. A GitHub pin outlives the package, so a reinstall is still compared with it; --forget-pin clears the pin too.

Environment

Errors and exit codes

Every action ends with one of three exit codesexit code The number a relate run returns to the shell; each nonzero value names a class of failure, such as 2 for usage, 5 for conflict, 6 for a rejected statement. Read more in the glossary.

When the channel index cannot be read, the message names its URL. This run had RELATE_EXTENSIONS_JSON_URL=http://127.0.0.1:8874/extensions.json with nothing listening; the text after io: comes from the operating system, and this recording is from macOS:

Error: extension list: could not read the extension channel index from http://127.0.0.1:8874/extensions.json: GET http://127.0.0.1:8874/extensions.json: io: Connection refused (os error 61)

Examples

The examples run in a fresh directory, written <dir>, with a fresh home, written <home>, and no XDG_CONFIG_HOME. Nothing is installed yet, so list prints nothing and exits 0:

relate extension list
echo "exit=$?"

exit=0

init scaffolds a package with a shell executable:

relate extension init team-import --lang sh

created sh extension 'team-import' in <dir>/team-import
  extension.json  the manifest (mount name, MCP revision, flag table)
  team-import.sh  the executable: generated glue plus your walk()
  README.md       the quickstart for this package

next:
  relate extension install team-import --from <dir>/team-import
  relate run team-import -d ./store

check runs it through the six stages without installing it. The initialize line names the binary's version:

relate extension check team-import

manifest: ok (team-import 0.1.0, protocol 2025-06-18)
executable: ok (team-import.sh)
spawn: ok
initialize: ok (MCP 2025-06-18, server relate 0.1.2)
notifications/initialized: ok
tools/list: ok (the shared tool table: 5 tools; the extension calls 'write_cypher')
pin: not from a GitHub source (unmarked)

install --from installs it as a local package, and list shows the tier and the source:

relate extension install team-import --from ./team-import
relate extension list

installed local extension team-import 0.1.0 from ./team-import
team-import 0.1.0 local ./team-import

A plain http URL to another host is refused before any fetch:

relate extension install other-import --url http://example.com/other-import.tar.gz
echo "exit=$?"

Error: extension install: --url accepts only https URLs (or plain http to the loopback interface); 'http://example.com/other-import.tar.gz' is neither
exit=2

remove deletes the installed package:

relate extension remove team-import

removed extension team-import (<home>/.config/relate/extensions/team-import)

See also

• relate run: running an installed extension into a store
• Install and run an extension: the tiers in practice
• Write an extension: from init to a working import
• Security: the release signing key the first-party channel shares with relate upgrade
• Problems relate solves: offline and sandboxed use: the commands that reach the network