--- id: "terminal-referencia-cli" titulo: "Referência de comandos do Terminal" resumo: "Os comandos de linha de comando que criam, listam, leem, alimentam e encerram sessões de terminal." idioma: "pt-br" 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/pt-br/ferramentas/terminal/referencia-cli/" fonte: "pt-br/ferramentas/terminal/referencia-cli.md" caminhoPublico: "docs/publica/pt-br/ferramentas/terminal/referencia-cli.md" hashFonte: "sha256:2b825534433de1d16cfc417d63160ecfc25d20bbd263a0b9ee27517a9815fbb8" hashDestaPagina: "sha256:2b825534433de1d16cfc417d63160ecfc25d20bbd263a0b9ee27517a9815fbb8" traducaoAssistidaPorIA: false traducaoDesatualizada: false corpoRetido: false --- Os comandos abaixo agem nas sessões da tela Terminal. Comandos, opções e valores são **literais** — não são traduzidos. ## Seletores e flags globais - **`--workspace `** — escolhe o workspace. Aceita `id:`, `name:`, `path:`, `active`/`current` e `focused`. - **`--worktree`** é **alias de compatibilidade** de `--workspace`. - Sem `--workspace`, a chamada local infere o workspace a partir do diretório atual. - **`--json`** devolve a saída estruturada. Use-a em automação: a saída legível prioriza a tela renderizada e pode não ser o que um programa deve interpretar. ## Comandos | Comando | Para que serve | |---|---| | `elyra terminal create` | Cria uma sessão de terminal no workspace atual | | `elyra terminal list` | Lista os terminais vivos gerenciados pelo Elyra | | `elyra terminal show` | Mostra metadados e uma prévia de um terminal | | `elyra terminal read` | Lê a saída retida de um terminal | | `elyra terminal send` | Envia entrada para um terminal vivo | | `elyra terminal wait` | Espera uma condição de terminal | | `elyra terminal split` | Divide um painel de terminal existente | | `elyra terminal rename` | Define ou limpa o título de uma aba | | `elyra terminal switch` | Troca para uma aba de terminal na interface | | `elyra terminal close` | Fecha uma aba de terminal (mata o processo, se estiver rodando) | | `elyra terminal replace` | Troca o agente que roda num terminal, mantendo o terminal | | `elyra terminal stop` | **Destrutivo:** encerra os terminais de um workspace | `elyra terminal focus` é **alias** de `elyra terminal switch`. ### Criar ``` elyra terminal create [--title ] [--command | --agent | --role [--prompt | --prompt-file ]] [--focus] [--json] ``` - Sem `--command`, `--agent` ou `--role`, abre um shell. - Cria a aba visível **sem trocar o foco** quando possível; se a interface não puder adotá-la, cai para um identificador em segundo plano. `--focus` troca para ela. - **Recusado quando a chamada vem de um cartão do Canvas**: um filho de agente de Canvas nasce como cartão, não como aba solta na tela Terminal. - `--prompt-file` aceita `-` para ler de stdin. No Windows, o lançador `.cmd` **trunca `--prompt` multilinha** na primeira quebra de linha — use arquivo. - `--role` inicia o agente com um papel salvo; um `--agent` explícito tem precedência sobre o papel. - Com `--agent`, o agente **ainda está subindo** quando o comando retorna. Escrever agora chega embaralhado no shell. - A saída carrega o identificador do terminal. **Fluxo recomendado depois de criar com agente:** ``` elyra terminal wait --terminal --for tui-idle elyra terminal send --terminal --text "" --enter elyra terminal read --terminal ``` ### Listar, detalhar e trocar ``` elyra terminal list [--workspace ] [--limit ] [--offset ] [--json] elyra terminal show [--terminal ] [--json] elyra terminal switch [--terminal ] [--json] ``` - `list` lista tudo do workspace. O servidor mantém um **teto interno de 200** como rede de segurança; `--limit`/`--offset` paginam apenas o que é exibido, localmente. `totalCount` continua cheio e **`truncated` diz a verdade** (corte do servidor **ou** corte da página local). - `show` e `switch` aceitam `--terminal `. ### Ler ``` elyra terminal read [--terminal | --node ] [--cursor ] [--limit ] [--lines ] [--all] [--workspace ] [--json] ``` - Sem `--cursor` e sem `--limit`, a CLI pagina a sessão retida e devolve tudo. - `--cursor` recebe o `nextCursor` de uma leitura anterior e traz **só o que é novo** desde então. - `--limit` pede uma página delimitada; a saída informa `oldestCursor` quando linhas mais antigas foram descartadas. - `--lines ` limita às últimas N linhas retidas — **teto de 2000 linhas por leitura**. `--all` devolve a sessão retida inteira — **até 20000 linhas**, com o mais antigo reportado por `truncated`. - Combinações proibidas: `--all` com `--lines`, `--cursor` ou `--limit`; `--lines` com `--cursor` ou `--limit`. - Alvo por `--terminal` **ou** `--node`, nunca os dois; sem nenhum, lê o terminal ativo. Use `--workspace` junto de `--node` para procurar o cartão fora do workspace atual. - **Cartão sem sessão viva falha** com aviso de que não há sessão viva, em vez de leitura vazia. - Leituras **sem** `--cursor` anexam a tela viva quando um agente ou aplicativo de tela alternativa tem viewport renderizado. A saída legível prioriza essa tela; o texto bruto continua em `--json` ou com `--cursor`. Shells seguem usando o final do buffer, e leituras com `--cursor` nunca trazem a tela viva. ### Enviar e esperar ``` elyra terminal send [--terminal ] [--text | --text-file ] [--enter] [--interrupt] [--json] elyra terminal wait [--terminal ] --for exit|tui-idle [--timeout-ms ] [--json] ``` - Use `--text-file` para textos de várias linhas: aspas de shell estragam quebras de linha e citações. `--text-file -` lê de stdin. - **Uma recusa de envio reprova o comando** com código de saída 1. - **Uma condição de espera não satisfeita também reprova o comando.** - `--interrupt` pode interromper trabalho ativo do agente. ### Dividir e renomear ``` elyra terminal split [--terminal ] [--direction horizontal|vertical] [--command ] [--json] elyra terminal rename [--terminal ] [--title ] [--json] ``` - `--direction` aceita **apenas** `horizontal` ou `vertical`; outro valor é recusado antes da chamada. - `rename` sem `--title` (ou com string vazia) volta ao título automático. ### Encerrar e substituir ``` elyra terminal close [--terminal ] [--json] elyra terminal stop --workspace [--json] elyra terminal replace [--terminal ] --agent [--prompt ] [--json] ``` > **`terminal stop` é DESTRUTIVO.** Mata o processo de **todo** terminal do workspace de uma vez — incluindo agentes no meio de uma tarefa — e **inclui o terminal de onde você está chamando**, se ele pertencer ao mesmo workspace. O que os processos não salvaram se perde. > > Para encerrar um só, use `elyra terminal close --terminal `. Para ver o que seria morto antes: `elyra terminal list --workspace `. - `close` mira uma aba e mata o processo dela se estiver rodando. - `stop` devolve **quantos** terminais foram encerrados. - `replace` mantém o identificador válido: mensagens de orquestração endereçadas ao terminal continuam funcionando, e o cartão do Canvas, a posição, as ligações e o título sobrevivem. **O estado em memória do processo anterior não é preservado**, e uma automação que reusava exatamente aquela sessão cai para uma sessão nova. - `replace` exige um agente conhecido; um agente desconhecido falha com erro de argumento.