Skip to main content

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​

FileShapeLifetime
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.jsonRecord<string, string> — static set @x onlyPersistent.
aliases.jsonRecord<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.jsonstring[] (symbols)Persistent.
fatfingers.jsonRecord<string, number> — symbol → max contractsPersistent.
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.logAppend-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.1Single 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 secretsPersistent.
cli.logLog linesAppended across CLI startups; logs --clear clears the active user's log.
market-data.dbSQLite — orderbook snapshots + recording configPersistent. See Recording.
cli_historyNewline-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 tasks view reads tasks.json instead, 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:

VariableEffect
TEALSTREET_CONFIG_DIRSet the root containing isolated profiles
TEALSTREET_CONFIG_FILESelect 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 ordinary hyrotrader challenge 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.

VariableEffect
TEALSTREET_TELEMETRY=0Turn 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.

CommandSurfaceContentFile
export / importREPL onlyVars + aliases (binds reserved)~/.tealstreet/cli-export.json
tealstreet accounts export / accounts importTop-level binary or REPLExchange account credentialsPath 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 the targets, capabilities, and optional API versions the script needs.
  • default async function (args, api) — the actual script body. api is the dispatcher's gate-checked surface, args carries 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.

See also​

  • Recording — market-data.db schema.
  • Listener — listener.json, trusted-clients.json, hooks.json.
  • Pairing — how trusted-clients.json gets populated.