> ## Documentation Index
> Fetch the complete documentation index at: https://docs.joystream.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuration

> Where the CLI stores its config and session, which environment variables it reads, and how each value is resolved.

## Files

```bash theme={null}
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:

```toml theme={null}
[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.

<Tabs>
  <Tab title="Config directory">
    1. `JOYSTREAM_CONFIG_DIR`, if set
    2. `~/.joystream/<stack>` — a per-checkout profile, used only once you have logged into that instance, meaning its `session.json` exists
    3. `~/.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.
  </Tab>

  <Tab title="API URL">
    1. `JOYSTREAM_API_URL`, if set
    2. `config.toml` `[backend].port`, resolved to `http://localhost:<port>`
    3. `http://localhost:8000`
  </Tab>

  <Tab title="Auth token">
    1. `JOYSTREAM_TOKEN`, for CI and scripting
    2. `session.json`, written by `jstm login`
    3. A legacy `config.toml` `[auth].token`
  </Tab>
</Tabs>

## 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:

```bash theme={null}
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:

```bash theme={null}
export JOYSTREAM_API_URL=https://api.example.com
export JOYSTREAM_TOKEN=$JOYSTREAM_CI_TOKEN
jstm agent conform ./invoice-summarizer --json --fail-on error
```