Config files
CLI state belongs to the signed-in user. The default root is
~/.tealstreet/ (~/.disrupt/ for Disrupt). Within it, files live under
profiles/<profile hash>/users/<user hash>/. The profile hash separates
brands, API origins and CONFIG_FILE profiles; the user hash separates
account IDs, including tenant prefixes. accounts prints the active
config directory, and logs uses the active user's log.
The files below are relative to that user's directory. They are plain text or SQLite; directory permissions restrict access to the operating-system user. This is profile isolation, not encryption against someone using the same operating-system account.
Login, logout and migration
Logging into B never relabels A's accounts, defaults, aliases, approvals, hooks or recording configuration. Returning to A restores A's profile. Logout removes the active profile's token, clears cached proxy tokens, disconnects exchanges and listeners, and cancels pending commands from the old login with a message. This includes queued exit/quit commands. In-flight scripts cannot make further adapter calls after their starting session ends. A new login reconnects the listener with that user's identity; browser approval is specific to that user.
Changing login stops the old user's in-process chasers and removes them from chase listings before disconnecting exchanges. Late chase results are discarded; they do not appear in the next user's chase watch or one-shot command result.
Pending account starts, retries, script captures, recorder completions and background update checks also stay bound to their starting login. Cross-trade startup stops its remaining account list on cancellation and disposes old connections without changing the new login's account activation flags. A switch discards their stale results, including when you switch back to the same user. The status bar clears, and the footer reloads the new user's saved settings.
Each legacy config can identify the owner of its own accounts. Shared legacy
files (hooks, browser approvals, vars, scripts and recordings) have one claim
for their physical source directory across config profiles, brands and path
aliases. They migrate only when the available ownership evidence is consistent;
competing config owners or a conflicting alias-sync owner leave them unclaimed.
Discovery checks config contents regardless of filename extension. Symlinks
are inspected only within the source directory; links outside it, broken links
and link loops leave shared ownership unproven and prevent shared migration.
An explicitly selected CONFIG_FILE symlink migrates its accounts, defaults and
login only when its target stays inside the source directory and ownership is
consistent. An unsafe or competing target stays quarantined and requires
re-entry; migration does not publish a completion marker after skipping it.
If an earlier version left an empty profile with a completion marker, the CLI
warns that re-entry is needed rather than overwriting that profile.
Files without ownership
evidence remain untouched and are never assigned to the next login: sign in
and re-enter the accounts/settings you need. Original legacy files remain
as backups; protect or remove those backups yourself when no longer needed.
The CLI does not load them again after migration. SQLite migration uses a
consistent snapshot, including committed WAL data.
Signed-out work uses a persistent local-only profile. Accounts, defaults, vars and aliases created there remain available to later signed-out invocations. That local profile is separate from authenticated profiles and is never imported on login. Pre-upgrade files with no ownership evidence still require re-entry.
Files
| File | Shape | Lifetime |
|---|---|---|
config.json | { defaultAccount, defaultSymbol, accounts: [...], auth: {...}, listener: { enabled?, accountSync?, remoteExec? }, footer: { enabled?, intervalMs?, segments?: [{ type, group?, text?, name?, color? }] } } | Persistent. Main config + creds. |
tasks.json | { version: 1, tasks: PersistedTask[] } | Persistent. Top-level tealstreet tasks view. |
cross-trade.json | { configs: StoredCrossTradeConfig[] } — each row extends safe-cex's CrossTradeConfig ({ enabled, masterAccount, masterSymbol?, masterWeight, copiers: CrossTradeCopier[] }) with id (uuid), updatedAt (ms), and optional deletedAt (tombstone). Read/written by tealstreet cross-trade {list,add,enable,disable,remove,run}. Same shape as the web side so the listener bridge can sync edits across runtimes. | Persistent. LWW + 30d tombstone retention. |
vars.json | Record<string, string> — static set @x only | Persistent. |
aliases.json | Record<string, string> | Persistent. |
aliases-sync.json | { cursor, pending[] } | Alias changes not yet accepted by the server, and the server revision seen. Deleting it re-syncs from scratch (the account's aliases win conflicts). |
whitelist.json | string[] (symbols) | Persistent. |
fatfingers.json | Record<string, number> — symbol → max contracts | Persistent. |
simulation.json | { enabled: boolean } | Persistent. |
budget.json | { usd: number } — aggregate notional cap (0 = off). Spend is session-only, not stored. | Persistent (cap only). |
audit.json | { enabled: boolean } — write-op audit log on/off (off by default). | Persistent. |
audit.log | Append-only JSONL — one { ts, runId?, account, command, ok, orderIds?, error? } per write-op while auditing is on; runId groups all writes from one typed line / repeat / script run, and [fill] lines attribute fills back to the placing command/run. | Append-only; size-capped (~5 MB) then rolled. |
audit.log.1 | Single rotated backup of audit.log (the previous ~5 MB). Replaced on each rotation. audit tail dips into it when the live log is short after a roll. | Overwritten on each rotation. |
cli-export.json | { version: 1, vars: {...}, aliases: {...}, binds: {} } | Written by the REPL export command. |
listener.json | { listenerId, createdAt } | Persistent. Identity for the loopback listener. |
trusted-clients.json | { clients: TrustedClient[] } | Persistent. Paired web clients. |
hooks.json | { hooks: Hook[] } — contains plaintext secrets | Persistent. |
cli.log | Log lines | Appended across CLI startups; logs --clear clears the active user's log. |
market-data.db | SQLite — orderbook snapshots + recording config | Persistent. See Recording. |
cli_history | Newline-separated commands (cap 1000) | Persistent. |
scripts/ | Directory. One .ts file per script + a seeded tsconfig.json, types.d.ts, and hello.ts example. | Persistent. See Scripts below. |
Session-only state
These are never written to disk. Restart the CLI and they're gone:
- Live vars (
sets @x …) — reactive variables that recompute on every read. - Tracked vars (
track max @x …/track min @x …) — ratchet trackers. - In-process chasers and TWAPs — running background tasks. The
top-level
tealstreet tasksview readstasks.jsoninstead, which is a separate persisted record. See Tasks.
If you want to round-trip your vars + aliases between machines, use
export / import below.
Overrides
Two environment variables relocate the state directory:
| Variable | Effect |
|---|---|
TEALSTREET_CONFIG_DIR | Set the root containing isolated profiles |
TEALSTREET_CONFIG_FILE | Select a separate profile; also identifies its legacy main config for migration |
With only CONFIG_FILE set, its parent directory is the profile root. Disrupt uses
DISRUPT_CONFIG_DIR / DISRUPT_CONFIG_FILE (with the documented Tealstreet fallbacks);
even identical overrides keep the brands separate.
Useful for sandboxed test setups (TEALSTREET_CONFIG_DIR=/tmp/ts-test tealstreet) or for keeping multiple identity configs on one machine.
Exchange endpoint overrides
Most exchange URLs are built into the CLI through safe-cex. HyroTrader defaults
to Hyro's hosted simulator at https://sim-tealstreet.hyro.site, and the standalone
CLI reads optional overrides from environment variables at process start:
NEXT_PUBLIC_HYROTRADER_PROD_REST_URL— HyroTrader production REST origin override for ordinaryhyrotraderchallenge accounts.NEXT_PUBLIC_HYROTRADER_PROD_PUBLIC_WS_URL— optional public WebSocket URL. Defaults to REST origin +/v5/public/linear.NEXT_PUBLIC_HYROTRADER_PROD_PRIVATE_WS_URL— optional private WebSocket URL. Defaults to REST origin +/v5/private.
Use the REST origin only, for example https://example.hyrotrader.invalid,
not a /v5/... endpoint path. These variables must be set in the shell that
launches tealstreet, or persisted in your shell profile if you want them
available every time.
NEXT_PUBLIC_HYROTRADER_SIMULATOR_* is reserved for the shared Tealstreet
demo/development simulator account and should not be used as a production
challenge template.
Crash reporting
Released binaries report crashes (uncaught exceptions and unhandled rejections) to Tealstreet's error tracker so we find breakage that never makes it into a bug report.
| Variable | Effect |
|---|---|
TEALSTREET_TELEMETRY=0 | Turn crash reporting off |
Also accepts false / off. Development runs (bun run src/index.ts)
never report — only versioned release binaries do.
What is sent: the exception type, message, and stack trace. Values that
look like credentials are redacted before the event leaves your machine,
and the hostname, OS username, request bodies, and account details are
not collected. Nothing from config.json or hooks.json is read by this
path.
Backing up
config.json and hooks.json are the sensitive ones — config.json
contains exchange API credentials, hooks.json contains webhook
secrets. Treat both like credentials. Don't sync them through anything
unencrypted. The CLI writes both, and account export output, as owner-only
(0600).
Back up the root only to a trusted location: profiles, legacy backups, history and scripts may also contain sensitive information. Exclusions must cover the nested user directories:
tar -czf tealstreet-backup.tar.gz \
--exclude='cli.log' \
--exclude='hooks.json' \
--exclude='config.json' \
~/.tealstreet
Restore by extracting back into ~/.tealstreet/.
Export / import
Two distinct round-trip flows exist. They do not overlap.
| Command | Surface | Content | File |
|---|---|---|---|
export / import | REPL only | Vars + aliases (binds reserved) | ~/.tealstreet/cli-export.json |
tealstreet accounts export / accounts import | Top-level binary or REPL | Exchange account credentials | Path you pass (or stdin/stdout) |
Use the first for moving your workflow setup between machines. Use the second for moving exchange creds — typically when seeding a new machine from the web app's exported account JSON.
See Aliases & vars → export/import for the workflow round-trip and Commands → Accounts for the credential round-trip.
Scripts
~/.tealstreet/scripts/ holds your custom Tealstreet scripts — one
.ts file per script, plus three seeded files the CLI manages.
On first launch the CLI creates the directory and writes:
tsconfig.json— TypeScript configuration so your editor picks up the ambient types. Only-if-missing; safe to edit.types.d.ts— ambient declarations for the script-facing API (api,args,ScriptMeta,Capabilities, etc.). Rewritten on every CLI launch so the surface stays in sync with the CLI version you're running — don't bother editing it, your changes will be overwritten.hello.ts— example script you can rename, edit, or delete. Only-if-missing.
Author a script by dropping a new .ts file into the directory.
Filenames must match /^[a-zA-Z_][a-zA-Z0-9_-]*$/ (letters, digits,
underscores, hyphens; no spaces, no dots). The filename sans .ts is
the script's name. Subdirectories are ignored. Names that collide with
REPL builtins (buy.ts, tasks.ts, etc.) are legal — see "Invoking a
script" below.
Each script must export:
meta: ScriptMeta— declares thetargets,capabilities, and optional API versions the script needs.default async function (args, api)— the actual script body.apiis the dispatcher's gate-checked surface,argscarries the parsed REPL arguments.
Invoking a script
The REPL routes scripts via the script:<name> prefix:
> script:hello
> script:hello arg1 --flag=value
The prefix is required. Bare hello is never resolved to a script —
it falls through to cli-core's regular command dispatcher, where it
either matches a builtin / user-defined alias / capture-variable name,
or finally errors as unknown if nothing matches. The prefix-only model
means filenames like buy.ts are perfectly legal: invoke them as
script:buy and the builtin buy keeps working unchanged.
script: composes with the rest of the chain syntax: retry N script:foo, @x = script:foo, set ec; script:foo, webhook fires
(hook create alert "script:foo 0.001 BTC"), and chain operators
(; and &).
After editing a script, run script reload in the REPL to re-scan
the directory. The CLI does not auto-reload on file save.