Getting started. Substrio docs

You need the CLI (substrio) and Node 18 or later. To move an existing backend instead, read bring-your-project.md after step 3.

npm install -g @substrio/cli
substrio --help

npx @substrio/cli login --email [email protected]

The CLI shows a short match code and opens a sign-in page in your browser. Check that the page shows the same match code, pass the bot check, and type the code from your email. Your browser is signed in to the dashboard, and the CLI saves the session to your profile. A new email address receives an account and a free plan at the same time.

If the CLI does not pick up the sign-in (you signed in on another device, for example), it exits after 100 seconds and asks for the code. Run substrio login --code <code> with the same code from your email. The session is refreshed automatically, so there is no key to copy. See agent-sessions.md for the whole flow.

2. Or log in with a key

substrio login --key - < key.txt

substrio login --key - reads a key from stdin and saves it to a profile. Without --url, the profile points to https://mcp.substrio.com. Pass --url to use an app's host. Use this option for a key you received another way, such as from the console or a teammate.

3. Create or pick an app

substrio app create myapp
substrio app list

substrio app create NAME creates an app under your account and saves its key to a profile named after it. substrio app list shows your existing apps, and substrio app get reads the app in the current profile using app.get. The record includes its hosts, domains, state, and limits. Subsequent pushes and calls target the app in your current profile. See accounts-and-apps.md.

4. Write and push a function

mkdir myapp && cd myapp
substrio init --yes

substrio init writes substrio.toml, functions/, public/, and a sample functions/hello.js. substrio.toml names a profile and does not contain a key. The file is explained in project-files.md.

substrio dev

substrio dev runs the project on the app's dev sandbox with hot reload. Each save runs there as a new version. The sandbox's logs stream to the terminal, and your live app does not change. Stop it with Ctrl+C.

substrio push -m "first version"

substrio push builds the project, uploads it as a new version, and runs it in the app's dev sandbox. You see the sandbox's address.

5. Try it on a sandbox or test host

substrio push prints the dev sandbox host, for example myapp--dev.substrio.com. Call your function there to test it before promotion. Export the current profile's key to a file and load it into your shell for the HTTP examples below. The file is readable only by its owner; keep it out of version control.

substrio key export --env .substrio-key.env
source .substrio-key.env

curl https://myapp--dev.substrio.com/v1/functions/hello/_invoke \
  -H "Authorization: Bearer $SUBSTRIO_KEY" -d '{"name":"world"}'

Bind a sandbox to a hostname of your own for a longer-lived preview: test-hosts.md.

6. Make it live

substrio promote

substrio promote makes the pushed version live (the data is backed up first). substrio rollback undoes a promote.

7. Call it

curl https://myapp.substrio.com/v1/functions/hello/_invoke \
  -H "Authorization: Bearer $SUBSTRIO_KEY" -d '{"name":"world"}'

mcp() { curl -s https://myapp.substrio.com/mcp -H "Authorization: Bearer $SUBSTRIO_KEY" \
  -H 'content-type: application/json' -d "$1"; }
mcp '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"substrio_function_invoke","arguments":{"name":"hello","event":{"name":"world"}}}}'

Every function is also callable over MCP with substrio_function_invoke, by the same key. See mcp.md and agents.md for connecting an agent instead of curl.

bring-your-project.md: move an existing backend.
project-files.md: substrio.toml and collections/*.json.
agents.md and mcp.md: AI agents.
cloud-functions.md: writing functions.

Getting started