Discovery
Let a client find the terminal's port and the token on its own, or pass them yourself.
A client needs two things: the port the terminal listens on and the token.
Terminal.discover() finds both.
Find the terminal
from spectre_terminal import Terminal
terminal = Terminal.discover()The token comes from the SPECTRE_LOCAL_API_TOKEN environment variable and
from nowhere else. The port comes from the terminal's instance.json file.
If the file is missing, the port is 48180. Then discover() makes one test
request.
When discovery fails
| What happens | What you get | What to do |
|---|---|---|
| No token is set | TokenMissing | Set SPECTRE_LOCAL_API_TOKEN |
| The API is switched off | LocalApiDisabled | Switch the API on |
| Nothing answers on the port | TerminalUnreachable | Start the terminal |
| The token is not the current one | ApiError with the code unauthorized | Copy the token again |
| The terminal has another API version | IncompatibleTerminal | See Compatibility |
These are the Python names. The TypeScript names end in Error, for example
TokenMissingError.
Set the port and the token yourself
import os
from spectre_terminal import Terminal
found = Terminal.discover(port=48181)
direct = Terminal(os.environ["SPECTRE_LOCAL_API_TOKEN"], port=48181)discover() with a port does not read instance.json. The constructor takes
the token and the port as given.
Use this for a second terminal on another port. One terminal on a machine is
the supported case. The host is always 127.0.0.1 or localhost.
Read the port without a client
A program in another language reads local_api_port from instance.json:
{ "pid": 108957, "http_port": 46727, "local_api_port": 48180 }| System | Path |
|---|---|
| Linux | $XDG_DATA_HOME/spectre-terminal/instance.json, by default ~/.local/share/spectre-terminal/instance.json |
| macOS | ~/Library/Application Support/spectre-terminal/instance.json |
| Windows | %LOCALAPPDATA%\spectre-terminal\instance.json |
local_api_port is missing or null while the API is off. Do not use
http_port: it is not the Local API.