When Fission starts a terminal session, it is not just rendering text. It is launching a real process and connecting it to a pseudo-terminal (PTY). A pseudo-terminal is an operating-system feature that makes a normal program think it is running inside a regular terminal window.

TerminalLaunchConfig is the typed way to describe how that process should start.

You do not need deep terminal knowledge to use it. The practical idea is simply: if your app wants to open a shell or run a command inside a terminal panel, this struct describes the startup settings.

Example

use std::path::PathBuf;
use fission::prelude::*;

let session = TerminalSession::spawn(TerminalLaunchConfig {
    cwd: Some(PathBuf::from("/Users/me/projects/my-app")),
    program: Some("git".into()),
    args: vec!["status".into()],
    env: vec![("RUST_LOG".into(), "debug".into())],
})?;

This example launches the git status command in a specific working directory.

Two Rust details are worth translating into plain English.

cwd: Some(...) means "use this working directory." Some is Rust's way of saying "a value is present." If you used None there instead, it would mean "do not set an explicit working directory here."

The ? at the end of the example means "if starting the terminal session fails, return that error." You can treat it as normal Rust error-handling scaffolding.

If you omit program, the implementation asks the host for the default shell or default terminal program instead.

Field reference

Field	Type	Meaning	Notes and default behavior
cwd	Option<PathBuf>	The working directory for the new process.	Defaults to None, which means no explicit directory is requested and the host default is used.
program	Option<String>	The program to launch inside the terminal session.	Defaults to None, which means the implementation asks for the default shell or default terminal program.
args	Vec<String>	Command-line arguments passed to program.	Defaults to an empty list. These are mainly useful when program names a specific command such as git or python.
env	Vec<(String, String)>	Extra environment variables to add before the process starts.	Defaults to an empty list. The runtime also sets TERM=xterm-256color and COLORTERM=truecolor for terminal behavior and color support.

What belongs here and what does not

Put startup choices here.

That includes things like the initial folder, the program name, a fixed command to run, or extra environment variables the process needs at launch.

Do not treat this struct as long-lived terminal state. Once the terminal session is running, the session itself owns the live process, terminal buffer, selection, and scrollback history. TerminalLaunchConfig is only the startup description.

Specific guidance

Create terminal sessions from a reducer, startup action, or another explicit application event. Do not call TerminalSession::spawn(...) from component conversion. Starting a terminal process is long-lived host work, not a pure user interface description.

If the user can choose the starting folder or program, keep those choices in app state and build the TerminalLaunchConfig from that state when it is time to launch the session.

Also remember that this is a host capability centered on local process execution. It is a strong fit for desktop-style products, but it is not the right starting point for browser-only work.

Production checklist

For TerminalLaunchConfig, review the fields that change behavior before treating the widget as finished: cwd, program, args, env. The goal is to make the product rule visible in state and actions, not hidden inside ad-hoc construction code.

•

If this widget appears inside an interactive flow, keep the surrounding action binding in the parent component and test that the flow still has one clear reducer path.

•

Check the semantics tree for the user-facing label or role that makes this widget understandable without relying only on pixels.

•

Add at least one component or harness test that confirms the visible text, semantic role, action dispatch, and layout constraint that matter for this widget in context.

If a screen starts repeating the same TerminalLaunchConfig setup, extract a named component around this widget. That keeps the reference API small while making product code easier to read and safer for generated code to copy.

TerminalSession, TerminalView, and Resources and async.