Referência: elyra workspace list

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.

elyra workspace list [--repo <selector>] [--limit <n>] [--json]

Flags aceitas no registro da CLI: --help, --json, --pairing-code, --environment, --repo, --limit.

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:

{
  "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

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.