---
id: "cli-workspace-list"
titulo: "Reference: elyra workspace list"
resumo: "Lists Elyra workspaces: flags, output and errors."
idioma: "en"
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/en/cli-workspace-list/"
fonte: "pt-br/cli-workspace-list.md"
caminhoPublico: "docs/publica/en/cli-workspace-list.md"
hashFonte: "sha256:601e0ec09c25a16bd7d55a98a419f30e267bef6e526f7a520b0f7714b4e808b2"
hashDestaPagina: "sha256:a27986ba8546181c6376e9b8c027331b2b3e2ee65cfc95a88a3407bf909cd6e3"
traducaoAssistidaPorIA: true
traducaoDesatualizada: false
corpoRetido: false
---
<!-- traducao-assistida-por-ia: idioma=EN fonte=pt-br/cli-workspace-list.md fonteHash=sha256:601e0ec09c25a16bd7d55a98a419f30e267bef6e526f7a520b0f7714b4e808b2 estado=atual -->

# `elyra workspace list`

Lists the **Elyra workspaces**. A workspace is a name and a folder inside a project — it is not a git worktree. Git worktrees belong to git and appear on the Git screen; this command never lists them.

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

Flags accepted by the CLI registry: `--help`, `--json`, `--pairing-code`, `--environment`, `--repo`, `--limit`.
<!-- fim:cli-workspace-list:gerado -->

## Before running

- **The app must be running.** The command queries the app runtime; with the app closed, the CLI returns `runtime_unavailable` and `Could not read Elyra runtime metadata at <profile>/elyra-runtime.json. Start the Elyra app first.`. `elyra agent-context --json` reads the local registry and works with the app closed.
- **Use the CLI belonging to the running installation.** `command -v elyra` shows the executable on PATH. Run the command **inside the open project's app terminal**. The same request from an external shell is refused with `agent_operation_denied`/`invalid_identity`: do not copy a session identity or bypass that protection.

## Flags

| Flag | Value | What it does |
|---|---|---|
| `--repo <selector>` | repository selector | filters the workspaces by project. Accepts `id:<id>`, `path:<path>` or `name:<name>`; without a prefix, it matches by exact id, path or display name. Without the flag, it lists all |
| `--limit <n>` | **positive** integer | caps how many are returned. Default: `200`. `0`, negative or non-integer is refused |
| `--json` | — | returns the JSON envelope instead of text |
| `--help` | — | command help |
| `--pairing-code`, `--environment` | value | CLI global flags (pairing and environment selection), accepted on any command |

CLI global flags: `--help`, `--json`, `--pairing-code`, `--environment`.

## What it returns

The response is the user's **visible** workspaces, optionally filtered by `--repo`, capped at `--limit` items. Along with it come:

- `totalCount` — how many workspaces matched, **before** the `--limit` cut;
- `truncated` — `true` when the cut happened.

That is: `--limit 5` with `truncated: true` and `totalCount: 12` means "I showed 5 of 12". The count never lies because of the cut.

Each workspace record carries identity, path, display name, kinship link to other workspaces (`parentWorktreeId` / `childWorktreeIds`), linked issue and comment — the same fields the sidebar uses.

## Text output

Without `--json`, the command prints one block per workspace: identity, branch and path on the first line, and the kinship, issue and comment fields on the following lines. An empty list prints `No worktrees found.` (the inherited text keeps the word `worktree`, although the records are workspaces).

When the `--limit` cut happens, the output ends with `truncated: showing <shown> of <total>`.

The structure below shows the shape of the text, with the values replaced by placeholders:

```
<workspace-id>  <branch>  <path>
displayName: <display name>
parentWorktreeId: <parent id | null>
childWorktreeIds: <comma-separated ids | []>
linkedIssue: <number | null>
comment: <comment>
```

Empty kinship fields appear as `null` and `[]`, never omitted — that is what makes it possible to tell "no parent" apart from "absent field".

## JSON output

The envelope is the same as the whole CLI's: identification of the call, `ok`, the `result` with `worktrees`/`totalCount`/`truncated`, and the runtime's `_meta`. The `hints` only exists in JSON — in text, this command does not print the next steps.

**Example output** with `--json`. IDs and paths are replaced; other workspace and envelope fields are omitted:

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

The reply also carries `_meta.runtimeId` and `hints`.

The `hints` of this command suggest:

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

## Observable errors

| Situation | Code | What the CLI shows |
|---|---|---|
| `--limit` is not a positive integer | `invalid_argument` | `Invalid positive integer for --limit` (non-numeric value: `Invalid numeric value for --limit`) |
| `--repo` matches no registered repository | `repo_not_found` | the code, plus the next step `elyra repo list --json` |
| `--repo` matches more than one repository | `selector_ambiguous` | the code, with the guidance to use a prefixed selector (`id:`) |
| App closed | `runtime_unavailable` | `Could not read Elyra runtime metadata at <profile>/elyra-runtime.json. Start the Elyra app first.` (path shortened here) |
| External shell without the app session identity | `agent_operation_denied` | `Refused: this session’s identity could not be confirmed by Elyra.`; run from the terminal or conversation that received the session |

Errors may include `nextSteps` in the JSON envelope.

## Related commands

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

| Command | What it is for |
|---|---|
| `elyra workspace show --workspace <selector> --json` | one workspace, by `id:`/`name:`/`path:`/`active`/`current`/`focused` |
| `elyra workspace current --json` | the workspace of the current folder |
| `elyra worktree list --json` | legacy name, read-only, same records |
| `elyra repo list --json` | registered repositories (what `--repo` can match) |

`worktree list` is the **legacy name** of `workspace list`: same handler, same records. The `branch:` and `issue:` selectors are no longer accepted by `workspace show`, and `--worktree` is still accepted as a compatibility alias of `--workspace`.

## Limits

- `--limit` cuts what is shown; there is no offset flag (`--offset`) in this command.