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 app --help prints the list below.

Most commands act on the app whose id is in ./matter.json. Pass --app <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 app create [dir] --space <space> --name <name> [--icon <emoji>] [--worker]`

Creates an app 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 with the SDK plugin and a dev port of the app’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 app dev as it changes. It keeps any file that’s already there, and refuses a folder whose matter.json already names an app. It then writes src/matter-app.d.ts, as matter app types does. Next: npm install, matter app dev, matter app deploy.

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

Creates the tables, fields, options and indexes that the schema names, in the app’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 app types [path]`

Writes the types for the SDK and the tables of the app’s space: to path, the types file in matter.json, or matter-app.d.ts. Run it again after the tables change. See Typed tables.

`matter app sdk [path]`

Writes a copy of the SDK module (default ./matter-sdk.js), for tests outside Matter. Pages don’t need it: Matter serves the SDK to them.

Developing

`matter app dev [--background] [--url <address>] [--command <command> | --no-command] [--worker <command> | --no-worker] [--app <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 app’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 app dev --stop. Use --no-command when your dev server is already running, and --no-worker to leave the worker out.

`matter app dev --stop [--app <id>]`

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

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

Prints the end of a log of the app’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 app env [--app <id>]`

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

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

The app must have been opened on this computer first.

`matter app open [--preview <deploymentId>] [--app <id>]`

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

Shipping

`matter app deploy [-m <message>] [--preview] [--key <key>] [--app <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 app 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 app 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 app deployments [--app <id>]`

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

`matter app promote <deploymentId> [--app <id>]`

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

`matter app pull [dir] [--app <id>]`

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

`matter app list`

Lists the apps in your workspaces, with their ids.

Routines

`matter app setup [--app <id>]`

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

`matter app routines [--app <id>]`

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

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

Runs one of your routines for the app now, by its key, with optional input. Set the app up first. With --dev, runs your dev routine of that key instead, while matter app 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 apps again with another key.