Referência de comandos do Terminal

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 <seletor> — escolhe o workspace. Aceita id:<id>, name:<nome>, path:<caminho>, 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 <nome>] [--command <texto> | --agent <id> | --role <nome> [--prompt <texto> | --prompt-file <caminho>]] [--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 <título|handle> --for tui-idle
elyra terminal send --terminal <título|handle> --text "<mensagem>" --enter
elyra terminal read --terminal <título|handle>

Listar, detalhar e trocar

elyra terminal list [--workspace <seletor>] [--limit <n>] [--offset <n>] [--json]
elyra terminal show [--terminal <título|handle>] [--json]
elyra terminal switch [--terminal <título|handle>] [--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 <título|handle>.

Ler

elyra terminal read [--terminal <título|handle> | --node <id|título>] [--cursor <n>] [--limit <n>] [--lines <n>] [--all] [--workspace <seletor>] [--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 <n> 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 <título|handle>] [--text <texto> | --text-file <caminho>] [--enter] [--interrupt] [--json]
elyra terminal wait [--terminal <título|handle>] --for exit|tui-idle [--timeout-ms <ms, máx. 3600000>] [--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 <título|handle>] [--direction horizontal|vertical] [--command <texto>] [--json]
elyra terminal rename [--terminal <título|handle>] [--title <texto>] [--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 <título|handle>] [--json]
elyra terminal stop --workspace <seletor> [--json]
elyra terminal replace [--terminal <handle|título>] --agent <id> [--prompt <texto>] [--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 <título|handle>. Para ver o que seria morto antes: elyra terminal list --workspace <seletor>.

• 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.