Terminal command reference

The commands below act on the sessions of the Terminal screen. Commands, options and values are literal — they are not translated.

Selectors and global flags

• --workspace <selector> — chooses the workspace. Accepts id:<id>, name:<name>, path:<path>, active/current and focused.
• --worktree is a compatibility alias of --workspace.
• Without --workspace, the local call infers the workspace from the current directory.
• --json returns structured output. Use it in automation: the readable output prioritizes the rendered screen and may not be what a program should parse.

Commands

Command	What it is for
elyra terminal create	Creates a terminal session in the current workspace
elyra terminal list	Lists the live Elyra-managed terminals
elyra terminal show	Shows metadata and a preview of one terminal
elyra terminal read	Reads a terminal’s retained output
elyra terminal send	Sends input to a live terminal
elyra terminal wait	Waits for a terminal condition
elyra terminal split	Splits an existing terminal panel
elyra terminal rename	Sets or clears a tab’s title
elyra terminal switch	Switches to a terminal tab in the interface
elyra terminal close	Closes a terminal tab (kills the process, if running)
elyra terminal replace	Swaps the agent running in a terminal, keeping the terminal
elyra terminal stop	Destructive: ends a workspace’s terminals

elyra terminal focus is an alias of elyra terminal switch.

Create

elyra terminal create [--title <name>] [--command <text> | --agent <id> | --role <name> [--prompt <text> | --prompt-file <path>]] [--focus] [--json]

• Without --command, --agent or --role, it opens a shell.
• Creates the visible tab without switching focus when possible; if the interface cannot adopt it, it falls back to a background handle. --focus switches to it.
• Refused when the call comes from a Canvas card: a child of a Canvas agent is born as a card, not as a loose tab on the Terminal screen.
• --prompt-file accepts - to read from stdin. On Windows, the .cmd launcher truncates a multi-line --prompt at the first line break — use a file.
• --role starts the agent with a saved role; an explicit --agent takes precedence over the role.
• With --agent, the agent is still starting up when the command returns. Writing now arrives scrambled in the shell.
• The output carries the terminal handle.

Recommended flow after creating with an agent:

elyra terminal wait --terminal <title|handle> --for tui-idle
elyra terminal send --terminal <title|handle> --text "<message>" --enter
elyra terminal read --terminal <title|handle>

List, inspect and switch

elyra terminal list [--workspace <selector>] [--limit <n>] [--offset <n>] [--json]
elyra terminal show [--terminal <title|handle>] [--json]
elyra terminal switch [--terminal <title|handle>] [--json]

• list lists everything in the workspace. The server keeps an internal ceiling of 200 as a safety net; --limit/--offset page only what is displayed, locally. totalCount stays full and truncated tells the truth (server cut or local page cut).
• show and switch accept --terminal <title|handle>.

Read

elyra terminal read [--terminal <title|handle> | --node <id|title>] [--cursor <n>] [--limit <n>] [--lines <n>] [--all] [--workspace <selector>] [--json]

• Without --cursor and without --limit, the CLI pages the retained session and returns everything.
• --cursor receives the nextCursor from a previous read and brings only what is new since then.
• --limit requests a bounded page; the output reports oldestCursor when older lines were discarded.
• --lines <n> limits to the last N retained lines — a ceiling of 2000 lines per read. --all returns the whole retained session — up to 20000 lines, with the oldest part reported through truncated.
• Forbidden combinations: --all with --lines, --cursor or --limit; --lines with --cursor or --limit.
• Target with --terminal or --node, never both; without either, it reads the active terminal. Use --workspace together with --node to look the card up outside the current workspace.
• A card with no live session fails with a notice that there is no live session, instead of an empty read.
• Reads without --cursor attach the live screen when an agent or alternate-screen application has a rendered viewport. The readable output prioritizes that screen; the raw text remains in --json or with --cursor. Shells keep using the end of the buffer, and reads with --cursor never carry the live screen.

Send and wait

elyra terminal send [--terminal <title|handle>] [--text <text> | --text-file <path>] [--enter] [--interrupt] [--json]
elyra terminal wait [--terminal <title|handle>] --for exit|tui-idle [--timeout-ms <ms, max 3600000>] [--json]

• Use --text-file for multi-line texts: shell quoting mangles newlines and quotes. --text-file - reads from stdin.
• A refused send fails the command with exit code 1.
• An unsatisfied wait condition also fails the command.
• --interrupt can interrupt the agent’s active work.

Split and rename

elyra terminal split [--terminal <title|handle>] [--direction horizontal|vertical] [--command <text>] [--json]
elyra terminal rename [--terminal <title|handle>] [--title <text>] [--json]

• --direction accepts only horizontal or vertical; another value is refused before the call.
• rename without --title (or with an empty string) goes back to the automatic title.

End and replace

elyra terminal close [--terminal <title|handle>] [--json]
elyra terminal stop --workspace <selector> [--json]
elyra terminal replace [--terminal <handle|title>] --agent <id> [--prompt <text>] [--json]

terminal stop is DESTRUCTIVE. It kills the process of every terminal in the workspace at once — including agents in the middle of a task — and includes the terminal you are calling from, if it belongs to the same workspace. Whatever the processes had not saved is lost.

To end a single one, use elyra terminal close --terminal <title|handle>. To see what would be killed first: elyra terminal list --workspace <selector>.

• close targets one tab and kills its process if it is running.
• stop reports how many terminals were ended.
• replace keeps the handle valid: orchestration messages addressed to the terminal keep working, and the Canvas card, its position, its edges and the title survive. The previous process’s in-memory state is not preserved, and an automation that reused exactly that session falls back to a new session.
• replace requires a known agent; an unknown agent fails with an argument error.