Command line¶
Every command and option of tensa, written from the program's own definitions. tensa --help and tensa COMMAND --help print the same text in a terminal.
tensa¶
Substrate for the ANDES power-system simulator GUI.
Usage: tensa [OPTIONS] COMMAND [ARGS]...
| Option | Value | Default | Description |
|---|---|---|---|
--version |
flag | Print the tensa and ANDES versions and exit. |
tensa serve¶
Run the tensa substrate.
Usage: tensa serve [OPTIONS]
| Option | Value | Default | Description |
|---|---|---|---|
--bind |
str | 127.0.0.1 |
Interface to bind. Default loopback. Non-loopback emits a stderr warning. |
--port |
int | 0 |
Port to listen on. 0 (default) lets the OS choose; the chosen port is bound before the app is built (so the Host/Origin allow-list matches it) and printed to stderr. |
--workspace |
path | ~/.tensa/cases |
Directory under which case files are stored. Created mode 0700 if missing. |
--max-sessions |
int | 4 |
Cap on concurrent sessions. |
--idle-timeout-seconds |
float | 180.0 |
Seconds without activity after which a session is closed. An open UI checks in every 30 seconds; keep this above 60. |
--sweep-workers |
int (min 1) | Most worker processes one sensitivity sweep may spread its iterations over. Default: the smaller of 4 and the number of CPUs. 1 runs every sweep on the session's own worker, one iteration after another. The bound is per sweep: sessions sweeping at once use that many times as many workers. | |
--allow-origin |
str | Additional CORS origin to accept (repeatable). Each value is added to BOTH the Host/Origin allow-list AND the FastAPI CORS allow-list so a Vite dev server (or similar) can talk to the substrate. Example: tensa serve --allow-origin http://127.0.0.1:5173. The host portion of each URL is also added to the Host allow-list. Repeat it to give several. |
|
--open |
flag | After the server starts listening, open the user's default browser at http://<host>:<port>/. Works with any --port, including the default OS-assigned one. |
|
--no-warm-cache |
flag | Do not check ANDES's generated code at startup. By default, when it is missing or has not been checked against the installed ANDES, the server runs tensa warm-cache in a background process. A case loaded while it runs waits for it; one loaded later does not wait for any generation. |
|
--log-level |
choice | info |
How much the server logs. info logs the startup, the serving URL and anything that goes wrong. debug adds one line for each HTTP request (method, path, status, time taken) and for each WebSocket. warning and above hide the serving URL. Upper or lower case both work. |
--log-file |
str | Also write the log to this file, which rotates at 5 MB and keeps three older ones. A name with no directory part, such as tensa.log, is written in ~/.tensa/logs; any other path is used as given. Created if missing; the server does not start if it cannot be written. | |
--log-json |
flag | Log one JSON object per line (time, level, logger, message, and exception when there is a traceback) instead of plain text, on stderr and in the --log-file. | |
--reload |
flag | DEV ONLY: auto-reload the server when files in the tensa package change (uvicorn reload). With the default --port 0 a free port is picked up front and reused across reloads. |
tensa desktop¶
Open TENSA in a window of its own instead of a browser tab.
Starts the server on a free port of this machine, which only this machine can reach, shows its UI in a native window, and stops the server when the window is closed. The sessions and their workers end with it. Apart from the window, everything works as it does under "tensa serve", and the options that both commands have are the same.
The window is pywebview's. Install it with pip install "tensa[desktop]" on Windows and macOS, and with pip install "tensa[desktop]" "pywebview[qt]" on Linux, where the window also needs a GUI toolkit that pywebview does not bring: Qt, which that command adds (on X11 it needs the system library libxcb-cursor0), or WebKitGTK and PyGObject from the distribution (a virtual environment sees them only when it was created with --system-site-packages).
Before it creates the workspace or starts the server, the command checks that a window can open here: that pywebview is installed and, on Linux, that there is a display and a toolkit that starts. When something is missing it says what, gives the command that installs it, and exits with status 1. "tensa serve --open" shows the same UI in a browser and needs none of this. Without a display, as over SSH, run "tensa serve" and open its address in a browser.
Usage: tensa desktop [OPTIONS]
| Option | Value | Default | Description |
|---|---|---|---|
--workspace |
path | ~/.tensa/cases |
Directory under which case files are stored. Created mode 0700 if missing. |
--max-sessions |
int | 4 |
Cap on concurrent sessions. |
--idle-timeout-seconds |
float | 180.0 |
Seconds without activity after which a session is closed. An open UI checks in every 30 seconds; keep this above 60. |
--sweep-workers |
int (min 1) | Most worker processes one sensitivity sweep may spread its iterations over. Default: the smaller of 4 and the number of CPUs. 1 runs every sweep on the session's own worker, one iteration after another. The bound is per sweep: sessions sweeping at once use that many times as many workers. | |
--no-warm-cache |
flag | Do not check ANDES's generated code at startup. By default, when it is missing or has not been checked against the installed ANDES, the server runs tensa warm-cache in a background process. A case loaded while it runs waits for it; one loaded later does not wait for any generation. |
|
--log-level |
choice | info |
How much the server logs. info logs the startup, the serving URL and anything that goes wrong. debug adds one line for each HTTP request (method, path, status, time taken) and for each WebSocket. warning and above hide the serving URL. Upper or lower case both work. |
--log-file |
str | Also write the log to this file, which rotates at 5 MB and keeps three older ones. A name with no directory part, such as tensa.log, is written in ~/.tensa/logs; any other path is used as given. Created if missing; the server does not start if it cannot be written. | |
--log-json |
flag | Log one JSON object per line (time, level, logger, message, and exception when there is a traceback) instead of plain text, on stderr and in the --log-file. | |
--width |
int (min 640) | 1280 |
Width of the window in pixels, at least 640. |
--height |
int (min 400) | 800 |
Height of the window in pixels, at least 400. |
--devtools |
flag | Open the web inspector (the developer tools of a browser) with the window, to see why the page misbehaves. |
tensa mcp¶
Run the MCP (Model Context Protocol) stdio server for LLM agents.
Exposes sessions, case loading, disturbances, power flow, TDS, and eigenanalysis as MCP tools. Requires the optional dependency: pip install "tensa[mcp]". Configure your MCP client to launch:
tensa mcp --workspace ~/tensa-cases
Usage: tensa mcp [OPTIONS]
| Option | Value | Default | Description |
|---|---|---|---|
--url |
str | Attach to an already-running tensa server (e.g. http://127.0.0.1:8000). | |
--workspace |
path | Spawn a private tensa server on an ephemeral loopback port serving this workspace for the lifetime of the MCP process. |
tensa warm-cache¶
Warm the ANDES symbolic-equation cache.
Runs andes.prepare() against the installed ANDES version. The
generated Python files land at ~/.andes/pycode/ (~1.5 MB total)
and are shared across all ANDES cases; subsequent andes.load
calls skip the cold-start prep.
Running this by hand is optional. Without a warm cache, the first case
you load pays the multi-minute prep cost, so tensa serve starts this
command in a background process when the cache is missing or has not been
checked against the installed ANDES (--no-warm-cache skips that). Run
it yourself to have the cache ready before the server starts:
pip install tensa
tensa warm-cache
tensa serve
After an ANDES upgrade ANDES regenerates the stale code on the next
andes.load; the check at startup, or this command, does it ahead of time.
Usage: tensa warm-cache [OPTIONS]
| Option | Value | Default | Description |
|---|---|---|---|
--quick |
flag | Run the faster, less-thorough code-generation pass. Useful in CI / quick smoke checks; the default is the full prep. | |
--incremental |
flag | Only regenerate models whose source changed since the last prep. Faster on top of an already-warm cache. |