logseq/docs/agent-guide/081-logseq-cli-list-node-subcommand.md

Logseq CLI list node Subcommand Implementation Plan

Goal: add a new list node subcommand to the existing logseq-cli surface so users can list ordinary nodes (both blocks and pages) filtered by tags and/or properties.

Architecture: keep the current logseq-cli -> command parse/build -> transport/invoke -> db-worker-node thread-api flow and implement filter query logic in db-worker helpers.

Architecture: reuse existing identifier resolution patterns from current CLI commands (especially tag/property resolution in add.cljs) instead of introducing a second resolver system.

Tech Stack: ClojureScript, babashka.cli, Datascript query/datoms, promesa, current formatter/command framework.

Related:

• /Users/rcmerci/gh-repos/logseq/docs/agent-guide/078-logseq-cli-task-subcommands.md
• /Users/rcmerci/gh-repos/logseq/docs/agent-guide/062-cli-list-default-sort-updated-at.md
• /Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md

Problem statement

Current CLI has list page, list tag, list property, and list task, but no generic list node path for querying ordinary content nodes by tag/property constraints.

Users need a first-class command that can return both pages and blocks, with script-friendly filter options:

• --tags <tag1>,<tag2>,<tag3>
• --properties <prop1>,<prop2>,<prop3>

Each filter item must support id / uuid / ident / block-name, and command execution must require at least one filter (--tags or --properties) to avoid returning unbounded node sets.

Current baseline from implementation

1) List command framework is centralized and reusable

/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/list.cljs already provides:

• list-common-spec (--expand, --fields, --limit, --offset, --sort, --order)
• shared helpers (apply-sort, apply-offset-limit, apply-fields)
• per-subcommand field maps and execute functions

This is the natural place to add list-node-spec, list-node-field-map, and execute-list-node.

2) db-worker list read logic already lives in one namespace

/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/common/db_worker.cljs holds list-pages, list-tags, list-properties, and list-tasks.

/Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs exposes them via :thread-api/cli-list-* endpoints.

A new list-nodes helper and :thread-api/cli-list-nodes should follow this same pattern.

3) Existing resolver utilities already cover most selector forms

/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/add.cljs already contains reusable resolution logic:

• tags: resolve-tag-entity / resolve-tags (supports id/uuid/ident/name through typed inputs)
• properties: resolve-property-identifiers with :allow-non-built-in? true (supports id/ident/name)

Gap to close for this plan:

• property selector by uuid is not currently supported in property resolver path and should be added for parity with the requested contract.

4) Command wiring and formatting are explicit and easy to extend

• Command dispatch/build/validation currently enumerates list commands in /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs.
• Human output table formatting for list commands is in /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs.
• Command parser and behavior tests already exist in:
  • /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs
  • /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/common/db_worker_test.cljs
  • /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs

Command contract

CLI syntax

logseq list node --graph <name> [--tags <csv>] [--properties <csv>] [common list options]

Required filters

At least one of the following must be present:

• --tags
• --properties

If both are missing, return :invalid-options with a clear message:

list node requires at least one of --tags or --properties

Filter options

--tags

--tags <tag1>,<tag2>,<tag3>

Each tag token supports:

• id (numeric)
• uuid
• ident (keyword form)
• block-name (tag page name)

--properties

--properties <prop1>,<prop2>,<prop3>

Each property token supports:

• id (numeric)
• uuid
• ident (keyword form)
• block-name (property page name)

Filter semantics

• CSV tokens are trimmed; blank tokens are ignored.
• After normalization, empty filter lists are invalid.
• --tags a,b means node must contain all resolved tag selectors.
• --properties x,y means node must contain all resolved property selectors.
• If both are provided, result must satisfy both groups (logical AND).

Node scope

list node returns ordinary content nodes of two kinds:

• pages
• blocks

Planned implementation should exclude schema-definition entities (for example, tag/property definition pages) so output focuses on content nodes.

Optional options (aligned with existing list commands)

list node should support the same common list options already used by existing list subcommands:

• --expand
• --fields <csv>
• --limit <n>
• --offset <n>
• --sort <field> (default updated-at)
• --order asc|desc

Proposed sortable/field keys for list node

MVP field map:

• id -> :db/id
• ident -> :db/ident
• title -> :block/title
• uuid -> :block/uuid
• type -> :node/type ("page" or "block")
• page-id -> :block/page-id (for blocks)
• page-title -> :block/page-title (for blocks)
• created-at -> :block/created-at
• updated-at -> :block/updated-at

Design details

A) CLI parsing and validation (list.cljs + commands.cljs)

1. Add list-node-field-map and list-node-spec in list.cljs.
2. Add new command entry:
   • [["list" "node"] :list-node ...]
3. Add CSV parser helper for selector options (--tags and --properties).
4. Extend invalid-options? handling so list node enforces required filter presence without changing behavior of existing list subcommands.
5. Wire :list-node through commands.cljs parse/build/execute branches.

B) Selector resolution strategy

Resolve filters in CLI layer before invoking db-worker:

• Tags:

  • normalize token to typed selector (id/uuid/ident/name)
  • resolve via existing tag resolver flow in add.cljs
  • pass resolved tag ids to db-worker

• Properties:

  • extend resolver support to include uuid-based property lookup
  • resolve to canonical property idents
  • pass resolved property idents to db-worker

This keeps db-worker focused on DB filtering, while CLI owns user-facing selector parsing/errors.

C) db-worker query strategy (db_worker.cljs)

Add list-nodes function with options shape like:

{:tag-ids [...]
 :property-idents [...]
 :expand true|false}

Implementation outline:

1. Build candidate ordinary-node set (pages + blocks, excluding schema-definition entities).
2. Apply tag intersection filter using :block/tags refs against resolved tag ids.
3. Apply property-presence intersection filter by checking node datoms for each resolved property ident.
4. Return minimal list item by default; include richer payload when :expand true.
5. Include :node/type and block page context fields for downstream formatting/fields selection.

D) thread-api exposure (db_core.cljs)

Add and wire:

• :thread-api/cli-list-nodes -> cli-db-worker/list-nodes

E) Output formatting (format.cljs)

Add list-node formatter branch with dedicated columns (including TYPE) and title width behavior identical to other list commands.

F) Completion/docs/e2e alignment

Update:

• command docs (docs/cli/logseq-cli.md)
• command summary/help tests
• optional completion tests if option specs affect completion surface
• CLI e2e inventory/cases for new command coverage

Step-by-step implementation plan (TDD first)

1. Add RED parser tests for list node command recognition and option parsing.
2. Add RED validation tests asserting list node fails without --tags and --properties.
3. Add RED tests for CSV parsing/normalization behavior for both filters.
4. Add RED resolver tests for tag/property selectors covering id/uuid/ident/block-name.
5. Add RED db-worker tests for node filtering semantics (all-of tags, all-of properties, combined AND).
6. Implement resolver extensions (including property uuid support).
7. Implement list-node-spec, command entry, action build, and execute path.
8. Implement cli-list-nodes thread-api and list-nodes db-worker helper.
9. Add/adjust formatter for human list-node output and structured output shape.
10. Update command docs and e2e inventory/cases.
11. Run focused tests, then full lint/test.

Files expected to change

Core implementation:

• /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/list.cljs
• /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/add.cljs (property uuid resolution support)
• /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs
• /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/common/db_worker.cljs
• /Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_core.cljs
• /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs

Tests:

• /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs
• /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/common/db_worker_test.cljs
• /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/format_test.cljs
• /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/completion_generator_test.cljs (if option completion changes)

Docs/e2e:

• /Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md
• /Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_inventory.edn
• /Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn

Testing plan

I will follow @test-driven-development and add failing tests before implementation changes.

Focused verification commands:

• bb dev:test -v logseq.cli.commands-test
• bb dev:test -v logseq.cli.common.db-worker-test
• bb dev:test -v logseq.cli.format-test
• bb dev:test -v logseq.cli.completion-generator-test (if touched)
• bb -f cli-e2e/bb.edn test --skip-build (if e2e specs changed)
• bb dev:lint-and-test

Risks and mitigations

Risk: property selector normalization can be ambiguous between ident and block-name.

Mitigation: define deterministic precedence (id -> uuid -> explicit keyword ident -> block-name fallback) and lock with tests.

Risk: filtering large graphs by multiple property idents can be slow.

Mitigation: use set-intersection style filtering and limit payload in non-expand mode.

Risk: “ordinary node” definition drift (schema entities leaking into output).

Mitigation: encode explicit exclusion rules in db-worker tests.

Acceptance criteria

1. logseq list node exists and is documented.
2. It returns both block and page nodes (ordinary content nodes).
3. --tags accepts comma-separated selectors and supports id/uuid/ident/block-name.
4. --properties accepts comma-separated selectors and supports id/uuid/ident/block-name.
5. At least one of --tags or --properties is required; otherwise command returns :invalid-options.
6. Common list options (--expand, --fields, --limit, --offset, --sort, --order) are supported.
7. Unit and e2e coverage is updated and green.

Open question

No blocking question for this phase.

---