Command line¶

CroStream has two programs you can run from a terminal:

crostream, the app itself. Without arguments it opens the desktop window; crostream serve runs it without a window for browser mode.
crostreamctl, a small terminal companion for machines with no screen: log in to Twitch, check the login, and watch chat and events scroll by.

crostream¶

crostream                 open the desktop app
crostream serve [options] run without a window and serve the UI to browsers

crostream serve¶

usage: crostream serve [-listen ADDR] [-host NAME:PORT]...

Option	Default	Meaning
`-listen ADDR`	`127.0.0.1:8080`	Where to serve the UI, the HTTP API and overlays. Use the machine's LAN address to reach it from other machines.
`-host NAME:PORT`	none	An extra name browsers may use, such as `streampc:8080`. Repeat for more names.
`-h`, `-help`		Print the usage and exit.

crostream serve -listen 192.168.1.50:8080 -host streampc:8080

It prints CroStream web UI: http://<address>/, and, when the address isn't this computer only, a reminder that there is no login. It runs until Ctrl+C or SIGTERM, then shuts down cleanly. The address must be given with -listen; a bare address as an argument is refused.

Exit code	Meaning
`0`	Stopped normally, or `-h`
`1`	Couldn't start: the address is taken or invalid, or CroStream is already running ("CroStream is already running on this computer. Close the other copy first.")
`2`	Bad options or arguments

crostream serve uses the same setup as the desktop app, and the two can't run at once. Everything about browser mode, including the allowed names and safety, is in Browser mode.

Internal subcommand

crostream screen-flash is a helper the app starts for itself to draw the screen flash effect. It isn't meant to be run by hand.

crostreamctl¶

crostreamctl runs only CroStream's Twitch connection (no OBS, no triggers or macros) against the same setup the app uses, so a login made with it is the app's login. It's a separate program, built alongside CroStream; it isn't part of the installers.

usage: crostreamctl [-config-dir DIR] <command> [flags]

commands:
  login                   log in through the browser (callback on localhost:62689)
  whoami                  show the logged-in account
  listen                  print live chat, redemptions, channel activity and notices (Ctrl-C to stop)

Global option	Meaning
`-config-dir DIR`	Use `DIR` instead of the app's config folder. It must come before the command. With it, the state (history, viewers) is kept in `DIR` too.

While CroStream is running

crostreamctl takes the same lock as the app. With the app's own folder, login works while the desktop app or crostream serve runs: it hands the login to the running app (see login). whoami and listen need their own Twitch connection, so while the app runs they stop with "CroStream is already running on this computer. Close the other copy first."; close the app first.

Exit code	Meaning
`0`	Done
`1`	The command failed; the reason follows `error:`
`2`	No command, or bad options; the usage is printed

crostreamctl login

Starts a Twitch login and prints a one-time link to open in a browser:

Open this one-time link in your browser and approve the login:
  http://localhost:62689/twitch/login?k=3f9c1d7e2b…
Waiting for the Twitch callback (Ctrl-C to abort)...

The link only works in a browser on the same machine, because Twitch returns to localhost:62689 there. Over SSH, crostreamctl reminds you to forward the port from your desktop first:

ssh -L 62689:127.0.0.1:62689 <this host>

When you approve the login on Twitch, it prints the account (as whoami does) and exits. Ctrl+C cancels. If you log in again to grant new permissions, see Logging in to Twitch.

While the app is running¶

If CroStream (the desktop app or crostream serve) is already running with the same folder, crostreamctl login doesn't stop with "already running". It asks the running app to start the login instead, prints the one-time link the app gives back, and exits:

CroStream is running, so it takes this login.

Open this one-time link in your browser and approve the login:
  http://localhost:62689/twitch/login?k=3f9c1d7e2b…
The app finishes the login when you approve it; its Twitch card shows the account.

Approve it in a browser on that machine, or through the SSH tunnel; the running app receives the callback and keeps the new login, with no restart. Check it on the app's Twitch page (whoami can't run while the app does).

How the hand-off works, for the curious:

The running app writes control.json to its state folder (with -config-dir, that folder) once its loopback server is listening, and removes it when it quits; a file left behind by a crash is cleared at the next start. The file is readable by your user only (mode 0600) and holds the app's local port and a random secret made fresh at every launch.
crostreamctl reads it and calls POST /control/twitch/login on the app's loopback server, sending the secret in the X-CroStream-Control header. A wrong or missing secret gets 401. The secret is never logged.
If the app is running but there's no control.json (an older version, for example), crostreamctl stops with the "already running" error and "(it offers no login hand-off; log in from the app)".

whoami¶

crostreamctl whoami

Connects to Twitch with the stored login and prints who it is:

State:    connected
Account:  crothers (broadcaster)
Expires:  2026-12-10 14:02:11 (in 1435h12m0s)
Scopes:   user:read:chat user:write:chat channel:manage:redemptions clips:edit …
Missing:  moderator:manage:warnings (log in again to grant)

Expires appears when the login has an expiry date; Missing lists permissions CroStream asks for that this login lacks. It waits up to 20 seconds for the connection; without a working login it fails with error: not connected (<state>): <reason>.

listen¶

crostreamctl listen

Prints chat, channel point redemptions, channel activity (follows, subs, cheers, raids…) and notices as they happen, until Ctrl+C:

Listening (Ctrl-C to stop)...
19:02:11  chat    PixelPanda[subscriber]   that was clean
19:02:40  redeem  LunarLily[subscriber]    "Hydrate" [unfulfilled] 
19:03:05  event   VelvetFox[everyone]      followed
19:03:30  status  connected

It only watches: no triggers fire and no macros run, so it's safe to run next to a copy of your setup. Control characters in chat are removed so viewers can't take over your terminal.

Check a copy of your config¶

Because -config-dir accepts any folder, you can try a copy of your setup without touching the real one, for example to check an upgrade or a restored backup:

Copy your config folder somewhere, such as ~/crostream-copy.

Run:

crostreamctl -config-dir ~/crostream-copy whoami

The copy is upgraded in place if it's from an older version, and its history and viewer databases are created in the same folder. A copy has its own lock, so this works while CroStream runs, but login with -config-dir needs port 62689 and can't run while CroStream holds it. See Upgrading.

Environment variables¶

CroStream reads these once, when it starts. They are for test rigs and automated runs, not everyday use.

Variable	Meaning
`CROSTREAM_SENTRY=off`	Turns crash reporting off, even in a development build (which otherwise always reports). The Settings panel then says Crash reporting is switched off by the CROSTREAM_SENTRY environment variable. and its switches do nothing. Any other value is ignored.
`CROSTREAM_SENTRY_DSN`	Replaces the address backend reports are sent to (a Sentry DSN), for pointing a test at your own Sentry project.
`CROSTREAM_SENTRY_UI_DSN`	The same for the app window's reports.

CROSTREAM_SENTRY=off crostream serve -listen 127.0.0.1:8081

Setting a DSN doesn't switch reporting on in a release build: the opt-in still applies.

Folders¶

Both programs find your setup in the usual places (see Where files are kept). On Linux, they follow XDG_CONFIG_HOME and XDG_STATE_HOME when set, so you can point a whole instance at other folders:

XDG_CONFIG_HOME=~/cs-test/config XDG_STATE_HOME=~/cs-test/state crostream serve -listen 127.0.0.1:8081