logseq/docs/agent-guide/022-logseq-cli-help-show-output.md

Logseq CLI Help and Show Output Cleanup Implementation Plan

Goal: Improve logseq-cli help readability and ensure show JSON and EDN outputs use :db/id without :block/uuid.

Architecture: The CLI help text is assembled in logseq.cli.command.core and babashka.cli spec descriptions, while show output is built in logseq.cli.command.show and formatted in logseq.cli.format before returning JSON or EDN.

Tech Stack: ClojureScript, logseq-cli, babashka.cli, db-worker-node.

Related: Relates to 018-logseq-cli-add-tags-builtin-properties.md.

Problem statement

The current help output lists [options] for nearly every command, which clutters the help display and reduces readability.

The tags and properties option help text does not clearly state that identifiers can be id, :db/ident, or :block/title across all relevant help contexts.

The show command includes :block/uuid in JSON and EDN output, even though :db/id is already present and preferred for programmatic consumers.

logseq-cli
  |  help text built from babashka.cli specs
  v
logseq.cli.command.core
  |  parse args and build command payloads
  v
logseq.cli.command.show
  |  fetch tree data from db-worker-node
  v
logseq.cli.format
  |  render human, json, edn output
  v
stdout

Testing Plan

I will add or update unit tests that assert help summaries do not include repeated [options] in the command list, and that tags and properties descriptions include the identifier guidance.

I will add or update unit tests that verify show JSON and EDN outputs do not include :block/uuid and still include :db/id for root and child nodes.

I will add or update integration tests for show JSON output to assert :db/id is present and :block/uuid is absent in root, tags, and linked references where applicable.

NOTE: I will write all tests before I add any implementation behavior.

Requirements

The top level help output and group summaries must avoid repeating [options] for each command listing while still documenting that options exist in the usage line.

The help description for --tags and --properties must explicitly state that identifiers can be id, :db/ident, or :block/title.

The show command must omit :block/uuid from JSON and EDN outputs while preserving :db/id for the same entities.

The show command human output must be unchanged.

Non-goals

Do not change CLI command behavior or supported flags beyond help text updates.

Do not change db-worker-node behavior or its API surface.

Do not change the structure of human output for show, list, add, or query commands.

Design decisions

Limit the help output adjustment to formatting in logseq.cli.command.core so command behavior and parsing remain unchanged.

Apply the identifier clarification to all --tags and --properties options in logseq.cli.command.add and any other specs that expose those flags.

Strip :block/uuid only for show outputs in JSON and EDN formats by post-processing tree data just before returning payloads.

Implementation plan

1. Follow @test-driven-development for every change in this plan.

2. Add a unit test in src/test/logseq/cli/commands_test.cljs that asserts command list rows in top level and group help do not contain [options] after the command name.

3. Add a unit test in src/test/logseq/cli/commands_test.cljs that asserts the --tags and --properties option descriptions include the text supporting id, :db/ident, and :block/title identifiers.

4. Add a unit test in src/test/logseq/cli/format_test.cljs or src/test/logseq/cli/commands_test.cljs that asserts show JSON and EDN outputs strip :block/uuid while retaining :db/id in root and child nodes.

5. Update integration tests in src/test/logseq/cli/integration_test.cljs that currently assert :uuid or :block/uuid in show JSON output to instead assert :db/id and absence of :block/uuid.

6. Adjust logseq.cli.command.core command listing formatting so only the usage line includes [options], and the command listing uses the bare command path without the suffix.

7. Update the --tags and --properties option descriptions in src/main/logseq/cli/command/add.cljs to include the identifier guidance sentence in a consistent phrasing.

8. Add a helper in src/main/logseq/cli/command/show.cljs or src/main/logseq/cli/format.cljs that removes :block/uuid keys from show JSON and EDN payloads, and apply it in execute-show when output-format is :json or :edn.

9. Run the updated unit tests and integration tests from the Testing Plan and confirm all pass.

Edge cases

Command help should still show [options] in the usage line for commands that accept options, but not in the command list table.

Multi-id show results should strip :block/uuid from each tree entry without changing the error map shape.

Linked references and tag entities should keep :db/id in the output even when :block/uuid is removed.

Testing Details

I will add tests that verify help summaries and option descriptions at the command summary level and not by matching the raw babashka.cli output.

I will add tests that parse show JSON and EDN output and assert :block/uuid is missing while :db/id remains on block nodes.

I will update integration tests that read show JSON output to match the new key expectations without changing the test setup logic.

Implementation Details

• Update logseq.cli.command.core formatting to render command rows without [options].
• Keep usage lines intact so users still see options availability in usage sections.
• Align help text for --tags and --properties to a single wording that mentions id, :db/ident, and :block/title.
• Add a show-specific sanitization step for json and edn output only.
• Keep the show tree data used for human output unchanged to avoid regressions.
• Ensure strip logic is recursive so :block/uuid is removed from nested children and linked references.
• Prefer clojure.walk/postwalk for key removal to minimize custom traversal code.
• Document the new behavior in tests rather than adding new user-facing docs.

Question

This is resolved. Only add supports --tags and --properties today, so we will update help text there only.

---