The matter command

The matter command comes with Matter and works as you, the member signed in to Matter on this computer. Matter must be running. Add its folder to your PATH to use it in your own terminal:

export PATH="$HOME/.matter/bin:$PATH"

On Windows, add %USERPROFILE%\.matter\bin to your Path; the command there is matter.cmd.

Agent threads in Matter have it already. matter extension --help prints the list below.

Most commands act on the extension whose id is in ./matter.json. Pass --extension <id> to name another. With several Matter accounts signed in on one computer, set MATTER_ACCOUNT to the user id of the one to use; otherwise matter uses the most recently started.

Creating

matter extension create [dir] --space <space> --name <name> [--icon <emoji>] [--worker]

Creates an extension in a space (by name or id) and scaffolds an empty project in dir, or the current folder: matter.json, schema.json, a Vite and TypeScript project that depends on the SDK’s package (@matter.work/extension-sdk), with the SDK plugin and a dev port of the extension’s own, index.html, src/main.ts, src/style.css, .gitignore and a README. With --worker, it adds a worker too: src/worker.ts, bundled into the deployment by npm run build, and run by matter extension dev as it changes. It keeps any file that’s already there, and refuses a folder whose matter.json already names an extension. It then writes src/matter-extension.d.ts, as matter extension types does. Next: npm install, matter extension dev, matter extension deploy.

matter table apply <schema.json> [--space <space>] [--prune]

Creates the tables, fields, options and indexes that the schema names, in the extension’s space unless you name another. It changes nothing that’s already there, and removes nothing. With --prune, it also deletes the indexes of the schema’s tables that the schema doesn’t name. See Tables and indexes.

matter extension types [path]

Writes the types for the tables of the extension’s space, which add them to the SDK’s own types in @matter.work/extension-sdk: to path, the types file in matter.json, or matter-extension.d.ts. Run it again after the tables change. See Typed tables.

matter extension sdk [path]

Writes the SDK module as this Matter serves it (default ./matter-sdk.js), to read. Extensions don’t need it: they import @matter.work/extension-sdk, which hands over to the copy Matter serves.

Developing

matter extension dev [--background] [--url <address>] [--command <command> | --no-command] [--worker <command> | --no-worker] [--extension <id>]

Starts your dev server (dev.command, or --command) and dev worker (dev.worker, or --worker), waits up to a minute for the dev server to answer at dev.url (or --url), then shows it in Matter in place of the extension’s deployment. The project’s routines run as your dev routines on this computer. It keeps your types file current while it runs, if you have one. See Developing.

In the foreground it shows the dev server’s and dev worker’s output, and Ctrl-C stops them. With --background it returns at once and keeps running, across closing the terminal and restarting Matter, until matter extension dev --stop. Use --no-command when your dev server is already running, and --no-worker to leave the worker out.

matter extension dev --stop [--extension <id>]

Stops the extension’s dev server, dev worker and dev routines. The extension goes back to its deployment.

matter extension logs [worker | run | dev-server | dev-worker] [--preview] [-n <lines>] [-f] [--extension <id>]

Prints the end of a log of the extension’s processes on this computer (50 lines, or -n), or of each log without a name. -f keeps printing what they write, until Ctrl-C. --preview shows a preview’s. See Logs.

matter extension env [--extension <id>]

Prints the environment the extension’s worker and tools get on this computer, as export lines, so you can run them yourself:

eval "$(matter extension env)"
node dist/worker.mjs

The extension must have been opened on this computer first.

matter extension open [--preview <deploymentId>] [--extension <id>]

Shows the extension in Matter. With --preview, shows a version that isn’t current.

Shipping

matter extension deploy [-m <message>] [--preview] [--key <key>] [--extension <id>]

Runs build, zips deploy.dir, signs it and uploads it. Without --preview, the new version becomes current for everyone. With --preview, it doesn’t: open it with matter extension open --preview <id>.

It signs with --key, else MATTER_SIGNING_KEY, else matter.json’s signingKey, else your default key, asking for the key’s passphrase if it has one (or reading MATTER_SIGNING_KEY_PASSPHRASE). See Signing keys.

Before uploading, it checks matter.json and tells you when:

• you have no signing key (it stops: matter keys create);
• minMatterVersion is missing (it stops);
• an entry file it names isn’t in the deployment (it stops);
• this computer’s Matter is outside the versions the extension supports;
• your types file is out of date with the space’s tables;
• there’s no index.html at the top of the deployment;
• a badge names a table or index that doesn’t exist.

The version records the message, and the git commit, branch and remote when the project is a git repository. Without -m, the message is the last commit’s.

matter extension deployments [--extension <id>]

Lists the extension’s 30 most recent versions, newest first, with * beside the current one.

matter extension promote <deploymentId> [--extension <id>]

Makes a version current: a preview, or an older version to roll back to.

matter extension pull [dir] [--extension <id>]

Downloads the current version’s files into dir, or the current folder.

matter extension list

Lists the extensions in your workspaces, with their ids.

Routines

matter extension setup [--extension <id>]

Sets the extension up for you on this computer: creates your member routines here.

matter extension routines [--extension <id>]

Lists your routines for the extension: key, title, schedule (or “on demand”), whether paused, and id.

matter extension run <routine> [--input <json>] [--dev] [--extension <id>]

Runs one of your routines for the extension now, by its key, with optional input. Set the extension up first. With --dev, runs your dev routine of that key instead, while matter extension dev runs.

Signing keys

Your keys are files in ~/.matter/keys. See Signing keys. Name a key by its name or fingerprint.

matter keys create [--name <name>] [--no-passphrase]

Makes a key, asking for a passphrase in a terminal (or using MATTER_SIGNING_KEY_PASSPHRASE), and registers it in your workspaces. Your first key becomes your default.

matter keys list

Your keys, with * beside the default, whether each has a passphrase, and where it’s registered; then keys you registered that aren’t on this computer.

matter keys default <key>

Signs with this key unless a deploy says otherwise.

matter keys export [<key>] [--private]

Prints the key’s name, fingerprint and public key. With --private, prints its file, to share the key with your team or give it to CI as MATTER_SIGNING_KEY.

matter keys import <file>

Keeps the key in a key file on this computer, registered in your workspaces as yours: a teammate’s shared key, say (one they registered stays theirs).

matter keys register [<key>]

Registers the key (your default) in your workspaces. Deploying with a key registers it too.

matter keys revoke <key>

Revokes the key in your workspaces, and moves its file to ~/.matter/keys/revoked if it’s here. The key can be one of yours on another computer, or, for a workspace admin, anyone’s. Matter stops trusting every version it signed, so deploy those extensions again with another key.