Reference: elyra workspace list

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.

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

Flags accepted by the CLI registry: --help, --json, --pairing-code, --environment, --repo, --limit.

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:

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

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.