opschain nodes list

Included from Basic tier

opschain nodes list [<path>] [--include-entities] [--kind <kind>] [--wide]

Lists the estate as a flat table, depth-first. With no argument it walks every project's subtree (projects first, children sorted by code); with a node path it lists that node and everything beneath it. Node paths are the usual demo, demo/environments/dev, demo/environments/dev/assets/web shapes — see opschain docs cli/nodes.

The walk reads each node's child collections from the server, so a large estate costs one request per node that can hold children. Entities are not part of that walk.

With --include-entities (a path is then required) the command instead reads the subtree in one call — the node hierarchy with its entities — and lists the node, its environments and assets, and every entity beneath them, nested at any depth, depth-first. The path may itself be an entity. Archived nodes are included, as in the walk. Rows from this read carry no description, created-by or maintenance (those columns show -); use nodes show for one node in full.

Flags

Flag	Meaning
--include-entities	Include the entities under the path, read in one hierarchy call. Requires a path.
--kind <kind>	Keep only nodes of this kind: project, environment, asset or entity (entity needs --include-entities). Applied after the read — the subtree is still traversed in full (filtering to asset still visits the projects and environments above them).
--wide	Add the DESCRIPTION and BY (created-by) columns.
--filter <column>[!]=<value>	Keep only rows matching the term (repeatable; terms AND). Columns are the printed table headers lowercased (spaces/dashes fold to _); * wildcards match the whole cell case-insensitively, != negates, commas mean any-of. Applied client-side after the walk, like --kind. Grammar: opschain docs cli.

Output

PATH                                      KIND         NAME            TEMPLATE            MAINTENANCE
/projects/demo                            project      Demo            -                   -
/projects/demo/environments/dev           environment  dev             -                   -
/projects/demo/environments/dev/assets/web  asset      web             web-template:1.0.0  -

• NAME carries an (archived) suffix on archived nodes.
• TEMPLATE is an asset's pinned template as <code>:<version> (- elsewhere); the asset collections are fetched with the template includes so it resolves on every listed asset.
• MAINTENANCE shows the reason of the node's maintenance badge (an active window covering the node, or a scheduled one starting within the server's badge horizon), - when none.

-o json / -o yaml print the same rows as an array of node objects (id, path, kind, code, name, description, archived, created_by, template, maintenance), the stable machine shape shared with nodes show.

Exit codes

Code	Meaning
0	Listed.
1	A server request failed, or (with --include-entities) the path is unknown or unreadable.
2	Usage error — bad path, bad --kind, no server target.

Named errors

• invalid --kind "…" (must be project, environment, asset or entity)
• --include-entities needs a node path — entities are listed under one subtree, e.g. opschain nodes list demo --include-entities
• --kind entity lists entities, which needs --include-entities and a node path
• expected a node path like demo, demo/environments/dev, /projects/demo/environments/dev/assets/web or demo/entities/rack_1, got "…"
• nodes operate on a server's estate — pass --server <url> or 'opschain context use <name>'

All exit 2.

Examples

opschain nodes list
opschain nodes list demo --kind asset
opschain nodes list demo/environments/dev --wide
opschain nodes list demo --include-entities
opschain nodes list demo/entities/building --include-entities --kind entity
opschain nodes list -o json

See also

• opschain docs cli/nodes-show — one node in full.
• opschain learn 1.1 — the estate, guided.