Configuration

Files

jstm init          # scaffold config.toml with a fresh encryption key
jstm init --force  # overwrite an existing config

Two files live in the resolved config directory.

File	Contents
`config.toml`	Backend URL, environment mode, encryption key, optional API keys
`session.json`	Your access token, refresh token, and expiry. Written with `0600` permissions

config.toml has these sections:

[supabase]
url = "..."
anon_key = "..."
service_role_key = ""      # only needed for jstm admin

[environment]
mode = "local"

[frontend]
port = 3001

[backend]
port = 8000

[encryption]
key = "..."                 # generated by jstm init

[anthropic]
api_key = ""                # optional

Resolution order

Three values are resolved by precedence, highest first.

Config directory
API URL
Auth token

JOYSTREAM_CONFIG_DIR, if set
~/.joystream/<stack> — a per-checkout profile, used only once you have logged into that instance, meaning its session.json exists
~/.joystream — the shared default

The per-checkout profile is how running jstm inside a particular checkout picks up that checkout’s login without disturbing your global session.

JOYSTREAM_API_URL, if set
config.toml [backend].port, resolved to http://localhost:<port>
http://localhost:8000

JOYSTREAM_TOKEN, for CI and scripting
session.json, written by jstm login
A legacy config.toml [auth].token

Session refresh

The CLI refreshes your token proactively when it is within 60 seconds of expiring. If the refresh fails, it clears the session and tells you to run jstm login again. A 401 from the backend produces the same message. A 403 does not — that means you’re signed in but not permitted, which signing in again won’t fix.

Environment variables

Variable	Effect
`JOYSTREAM_API_URL`	Backend base URL. Highest precedence
`JOYSTREAM_CONFIG_DIR`	Override the config and session directory
`JOYSTREAM_TOKEN`	Bearer token, bypassing the session file
`JOYSTREAM_DEBUG`	Log the full traceback to stderr and raise the log level to debug
`JOYSTREAM_LOG_LEVEL`	Set an explicit log level. Overrides `JOYSTREAM_DEBUG`

The CLI also honors the usual terminal conventions: NO_COLOR, COLUMNS, and TERM.

Multiple instances

Because the config directory is resolvable per environment, you can point the CLI at different backends without logging in and out:

JOYSTREAM_CONFIG_DIR=~/.joystream/staging jstm login
JOYSTREAM_CONFIG_DIR=~/.joystream/staging jstm whoami

In CI

Set both the URL and a token, and skip interactive login entirely:

export JOYSTREAM_API_URL=https://api.example.com
export JOYSTREAM_TOKEN=$JOYSTREAM_CI_TOKEN
jstm agent conform ./invoice-summarizer --json --fail-on error

Using the CLI

Commands

Files

Resolution order

Session refresh

Environment variables

Multiple instances

In CI

​Files

​Resolution order

​Session refresh

​Environment variables

​Multiple instances

​In CI

Files

Resolution order

Session refresh

Environment variables

Multiple instances

In CI