--- id: "terminal-referencia-cli" titulo: "Terminal command reference" resumo: "The command-line commands that create, list, read, feed and end terminal sessions." idioma: "en" tipo: "referencia" categoria: "telas" aplicavelDesde: "0.0.16" capabilities: ["terminal.sessions.create", "terminal.sessions.discover", "terminal.output.read", "terminal.input.send", "terminal.layout.split", "terminal.sessions.rename", "terminal.sessions.end"] estadoEditorial: "aprovado" nivelEvidencia: "artefato-distribuido" refFonte: "27574c339b58316408f6be2d62169d59041d07bf" revisaoFonte: "2026-09-24" revisor: "mantenedor (v1, 2026-10-03)" rota: "/docs/en/ferramentas/terminal/referencia-cli/" fonte: "pt-br/ferramentas/terminal/referencia-cli.md" caminhoPublico: "docs/publica/en/ferramentas/terminal/referencia-cli.md" hashFonte: "sha256:2b825534433de1d16cfc417d63160ecfc25d20bbd263a0b9ee27517a9815fbb8" hashDestaPagina: "sha256:bbfe839be49433f2a6c4e994e0130705fd37d392bd313e303857c345ed4ee296" traducaoAssistidaPorIA: true traducaoDesatualizada: false corpoRetido: false --- 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 `** — chooses the workspace. Accepts `id:`, `name:`, `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 ] [--command | --agent | --role [--prompt | --prompt-file ]] [--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 --for tui-idle elyra terminal send --terminal --text "" --enter elyra terminal read --terminal ``` ### List, inspect and switch ``` elyra terminal list [--workspace ] [--limit ] [--offset ] [--json] elyra terminal show [--terminal ] [--json] elyra terminal switch [--terminal ] [--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 `. ### Read ``` elyra terminal read [--terminal | --node ] [--cursor ] [--limit ] [--lines ] [--all] [--workspace ] [--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 ` 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 ] [--text | --text-file ] [--enter] [--interrupt] [--json] elyra terminal wait [--terminal ] --for exit|tui-idle [--timeout-ms ] [--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 ] [--direction horizontal|vertical] [--command ] [--json] elyra terminal rename [--terminal ] [--title ] [--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 ] [--json] elyra terminal stop --workspace [--json] elyra terminal replace [--terminal ] --agent [--prompt ] [--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 `. To see what would be killed first: `elyra terminal list --workspace `. - `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.