---
id: "cli-workspace-list"
titulo: "Referência: elyra workspace list"
resumo: "Lista os workspaces do Elyra: flags, saída e erros."
idioma: "pt-br"
tipo: "referencia"
categoria: "fundamentos"
aplicavelDesde: "0.0.16"
capabilities: ["workspaces.list"]
estadoEditorial: "aprovado"
nivelEvidencia: "artefato-distribuido"
refFonte: "27574c339b58316408f6be2d62169d59041d07bf"
revisaoFonte: "2026-09-24"
revisor: "mantenedor (v1, 2026-10-03)"
rota: "/docs/pt-br/cli-workspace-list/"
fonte: "pt-br/cli-workspace-list.md"
caminhoPublico: "docs/publica/pt-br/cli-workspace-list.md"
hashFonte: "sha256:601e0ec09c25a16bd7d55a98a419f30e267bef6e526f7a520b0f7714b4e808b2"
hashDestaPagina: "sha256:601e0ec09c25a16bd7d55a98a419f30e267bef6e526f7a520b0f7714b4e808b2"
traducaoAssistidaPorIA: false
traducaoDesatualizada: false
corpoRetido: false
---
# `elyra workspace list`

Lista os **workspaces do Elyra**. Um workspace é um nome e uma pasta dentro de um projeto — não é um worktree do git. Worktrees do git pertencem ao git e aparecem na tela Git; este comando nunca os lista.

<!-- inicio:cli-workspace-list:gerado -->
```bash
elyra workspace list [--repo <selector>] [--limit <n>] [--json]
```

Flags aceitas no registro da CLI: `--help`, `--json`, `--pairing-code`, `--environment`, `--repo`, `--limit`.
<!-- fim:cli-workspace-list:gerado -->

## Antes de rodar

- **O app precisa estar no ar.** O comando consulta o runtime do app; com o app fechado, a CLI devolve `runtime_unavailable` e `Could not read Elyra runtime metadata at <perfil>/elyra-runtime.json. Start the Elyra app first.`. `elyra agent-context --json` consulta o registro local e funciona com o app fechado.
- **Use a CLI da instalação em uso.** `command -v elyra` mostra o executável no PATH. Rode o comando **no terminal do projeto aberto no app**. Em um shell externo, a mesma chamada é recusada com `agent_operation_denied`/`invalid_identity`: não copie identidade de sessão nem tente contornar essa proteção.

## Flags

| Flag | Valor | O que faz |
|---|---|---|
| `--repo <selector>` | seletor de repositório | filtra os workspaces por projeto. Aceita `id:<id>`, `path:<caminho>` ou `name:<nome>`; sem prefixo, casa por id, caminho ou nome de exibição exatos. Sem a flag, lista todos |
| `--limit <n>` | inteiro **positivo** | corta a quantidade devolvida. Padrão: `200`. `0`, negativo ou não inteiro é recusado |
| `--json` | — | devolve o envelope JSON em vez do texto |
| `--help` | — | ajuda do comando |
| `--pairing-code`, `--environment` | valor | flags globais da CLI (pareamento e seleção de ambiente), aceitas em qualquer comando |

Flags globais da CLI: `--help`, `--json`, `--pairing-code`, `--environment`.

## O que ele devolve

A resposta é a lista de workspaces **visíveis** do usuário, opcionalmente filtrada por `--repo`, cortada em `--limit` itens. Junto vêm:

- `totalCount` — quantos workspaces casaram, **antes** do corte de `--limit`;
- `truncated` — `true` quando o corte aconteceu.

Ou seja: `--limit 5` com `truncated: true` e `totalCount: 12` significa "mostrei 5 de 12". A contagem nunca mente por causa do corte.

Cada registro de workspace traz identidade, caminho, nome de exibição, vínculo de parentesco com outros workspaces (`parentWorktreeId` / `childWorktreeIds`), issue ligada e comentário — os mesmos campos que a barra lateral usa.

## Saída em texto

Sem `--json`, o comando imprime um bloco por workspace: identidade, branch e caminho na primeira linha, e os campos de parentesco, issue e comentário nas linhas seguintes. Lista vazia imprime `No worktrees found.` (o texto herdado mantém a palavra `worktree`, embora os registros sejam workspaces).

Quando o corte de `--limit` acontece, a saída termina com `truncated: showing <mostrados> de <total>`.

A estrutura abaixo mostra a forma do texto, com os valores substituídos por marcadores:

```
<workspace-id>  <branch>  <caminho>
displayName: <nome de exibição>
parentWorktreeId: <id do pai | null>
childWorktreeIds: <ids separados por vírgula | []>
linkedIssue: <número | null>
comment: <comentário>
```

Campos de parentesco vazios aparecem como `null` e `[]`, nunca omitidos — é o que permite distinguir "sem pai" de "campo ausente".

## Saída em JSON

O envelope é o mesmo de toda a CLI: identificação da chamada, `ok`, o `result` com `worktrees`/`totalCount`/`truncated`, e o `_meta` do runtime. O `hints` só existe no JSON — no texto, os próximos passos não são impressos por este comando.

**Exemplo de saída** com `--json`. IDs e caminhos foram substituídos; outros campos do workspace e do envelope foram omitidos:

```json
{
  "ok": true,
  "result": {
    "worktrees": [{ "id": "<workspace-descartável>", "displayName": "master", "path": "<pasta-descartável>" }],
    "totalCount": 1,
    "truncated": false
  }
}
```

O retorno também traz `_meta.runtimeId` e `hints`.

O `hints` deste comando sugere:

```
elyra canvas list --workspace <selector> --json
elyra terminal list --workspace <selector> --json
```

## Erros observáveis

| Situação | Código | O que a CLI mostra |
|---|---|---|
| `--limit` não é inteiro positivo | `invalid_argument` | `Invalid positive integer for --limit` (valor não numérico: `Invalid numeric value for --limit`) |
| `--repo` não casa com nenhum repositório registrado | `repo_not_found` | o código, mais o próximo passo `elyra repo list --json` |
| `--repo` casa com mais de um repositório | `selector_ambiguous` | o código, com a orientação de usar um seletor com prefixo (`id:`) |
| App fechado | `runtime_unavailable` | `Could not read Elyra runtime metadata at <perfil>/elyra-runtime.json. Start the Elyra app first.` (caminho abreviado aqui) |
| Shell externo sem identidade da sessão do app | `agent_operation_denied` | `Refused: this session’s identity could not be confirmed by Elyra.`; rode no terminal/conversa que recebeu a sessão |

Os erros podem trazer `nextSteps` no envelope JSON.

## Comandos relacionados

```bash
elyra workspace show --workspace <selector> --json
elyra workspace current --json
elyra worktree list --json
elyra repo list --json
```

| Comando | Para que serve |
|---|---|
| `elyra workspace show --workspace <selector> --json` | um workspace, por `id:`/`name:`/`path:`/`active`/`current`/`focused` |
| `elyra workspace current --json` | o workspace da pasta atual |
| `elyra worktree list --json` | nome legado, somente leitura, mesmos registros |
| `elyra repo list --json` | repositórios registrados (o que `--repo` pode casar) |

`worktree list` é o **nome legado** de `workspace list`: mesmo handler, mesmos registros. Os seletores `branch:` e `issue:` não são mais aceitos por `workspace show`, e `--worktree` continua aceito como alias de compatibilidade de `--workspace`.

## Limites

- `--limit` corta o que é mostrado; não há flag de deslocamento (`--offset`) neste comando.