---
id: "sistema.referencia-cli-inspecao"
titulo: "Inspecionar comandos e contexto"
resumo: "Referência de dois comandos de leitura: o registro de comandos e a descoberta de onde você está."
idioma: "pt-br"
tipo: "referencia"
categoria: "ajustes"
aplicavelDesde: "0.0.16"
capabilities: ["settings.cli.schema", "settings.cli.context"]
estadoEditorial: "aprovado"
nivelEvidencia: "artefato-distribuido"
refFonte: "27574c339b58316408f6be2d62169d59041d07bf"
revisaoFonte: "2026-09-24"
revisor: "mantenedor (v1, 2026-10-03)"
rota: "/docs/pt-br/sistema/referencia-cli-inspecao/"
fonte: "pt-br/sistema/referencia-cli-inspecao.md"
caminhoPublico: "docs/publica/pt-br/sistema/referencia-cli-inspecao.md"
hashFonte: "sha256:9072bef79aadd970bdd6ff723a40d6c5f525ad9e3964eba4c8e2b57b6c4cff2d"
hashDestaPagina: "sha256:9072bef79aadd970bdd6ff723a40d6c5f525ad9e3964eba4c8e2b57b6c4cff2d"
traducaoAssistidaPorIA: false
traducaoDesatualizada: false
corpoRetido: false
---
Dois comandos de **leitura pura** que ajudam a descobrir o que existe e onde você está. Nenhum dos dois
altera nada.

## `elyra agent-context`

```
elyra agent-context [--json]
```

Imprime o **registro de comandos** em formato legível por máquina: comandos, argumentos e opções
conhecidos.

| Característica | Detalhe |
|---|---|
| **Leitura local pura** | Não precisa do app em execução |
| **Seguro em contexto remoto** | Funciona por SSH e em ambiente sem interface |
| **O que ele descreve** | **Comandos, argumentos e flags** — não os resultados |

> **Não infira a API do produto a partir deste registro.** Ele descreve a superfície de comandos; ele
> **não** representa o formato de resposta de cada comando, nem é um contrato de API HTTP.

## `elyra context`

```
elyra context [--json]
```

Diz **onde você está**. Duas informações diferentes vêm juntas:

| Campo | O que significa |
|---|---|
| `screen` | A **tela que a pessoa está olhando** agora: Canvas, Conversa, Terminal ou Navegador |
| `caller.surface` | **Onde você está hospedado**: `canvas` (você é um cartão) ou `terminal` (você é uma aba da tela Terminal) |

**Os dois podem discordar.** É exatamente por isso que são campos separados: a pessoa pode estar olhando
o Canvas enquanto o processo roda numa aba de Terminal.

Fora de um terminal do Elyra, `caller.surface` vem como `unknown` e não existe cartão — **nada falha por
causa disso**.

### A regra prática

Rode `elyra context` **antes** de criar um terminal, uma conversa ou uma nota:

- Com `screen=canvas` **ou** `caller.surface=canvas`, prefira criar um **cartão** no Canvas.
- Caso contrário, criar uma **aba** de Terminal é o caminho.

## Resultado

- Você sabe quais comandos existem e quais opções cada um aceita.
- Você sabe a diferença entre a tela visível e a superfície onde o processo vive.

## Limites

- **O registro não é um schema de saída.** Ele não descreve o JSON de resposta dos comandos.
- **Não adivinhe a superfície pela tela.** Especialmente em SSH, ou numa sessão que continua rodando
  depois de você trocar de tela.
- **O comando `context` não falha fora do app.** Ele devolve `unknown` e segue.

## Próximos passos

- [Ajustes](/docs/pt-br/sistema/ajustes/)
- [Avançado](/docs/pt-br/sistema/avancado/)