---
id: "sistema.referencia-cli-inspecao"
titulo: "Inspecting commands and context"
resumo: "Reference for two read-only commands: the command registry and the discovery of where you are."
idioma: "en"
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/en/sistema/referencia-cli-inspecao/"
fonte: "pt-br/sistema/referencia-cli-inspecao.md"
caminhoPublico: "docs/publica/en/sistema/referencia-cli-inspecao.md"
hashFonte: "sha256:9072bef79aadd970bdd6ff723a40d6c5f525ad9e3964eba4c8e2b57b6c4cff2d"
hashDestaPagina: "sha256:bbfd6361c2582077f42b5cb782b1960d8bcf9c65e8af82b4bb0bc00fbf57dc58"
traducaoAssistidaPorIA: true
traducaoDesatualizada: false
corpoRetido: false
---
<!-- traducao-assistida-por-ia: idioma=EN fonte=pt-br/sistema/referencia-cli-inspecao.md fonteHash=sha256:9072bef79aadd970bdd6ff723a40d6c5f525ad9e3964eba4c8e2b57b6c4cff2d estado=atual -->

Two **pure-read** commands that help you find out what exists and where you are. Neither of them changes
anything.

## `elyra agent-context`

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

It prints the **command registry** in machine-readable form: commands, arguments and known options.

| Characteristic | Detail |
|---|---|
| **Pure local read** | Does not need the app running |
| **Safe in a remote context** | Works over SSH and in an environment without an interface |
| **What it describes** | **Commands, arguments and flags** — not the results |

> **Do not infer the product's API from this registry.** It describes the command surface; it does **not**
> represent the response format of each command, nor is it an HTTP API contract.

## `elyra context`

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

It says **where you are**. Two different pieces of information come together:

| Field | What it means |
|---|---|
| `screen` | The **screen the person is looking at** right now: Canvas, Conversation, Terminal or Browser |
| `caller.surface` | **Where you are hosted**: `canvas` (you are a card) or `terminal` (you are a tab of the Terminal screen) |

**The two can disagree.** That is exactly why they are separate fields: the person may be looking at the
Canvas while the process runs in a Terminal tab.

Outside an Elyra terminal, `caller.surface` comes as `unknown` and there is no card — **nothing fails
because of that**.

### The practical rule

Run `elyra context` **before** creating a terminal, a conversation or a note:

- With `screen=canvas` **or** `caller.surface=canvas`, prefer creating a **card** on the Canvas.
- Otherwise, creating a Terminal **tab** is the way.

## Result

- You know which commands exist and which options each one accepts.
- You know the difference between the visible screen and the surface where the process lives.

## Limits

- **The registry is not an output schema.** It does not describe the commands' response JSON.
- **Do not guess the surface from the screen.** Especially over SSH, or in a session that keeps running
  after you switch screens.
- **The `context` command does not fail outside the app.** It returns `unknown` and moves on.

## Next steps

- [Settings](/docs/en/sistema/ajustes/)
- [Advanced](/docs/en/sistema/avancado/)