logseq/docs/agent-guide/070-logseq-cli-example-subcommand.md

Logseq CLI example Subcommand Implementation Plan

Goal: Add a new example command group so users can ask for runnable command examples by command path or command prefix, for example:

• logseq example upsert page
• logseq example upsert
• logseq example show
• logseq example search block

Phase 1 scope is limited to all commands in the current Graph Inspect and Edit group.

Architecture: Keep this feature CLI-only in phase 1. Reuse command metadata already defined in logseq-cli command entries (:examples) and do not add any new db-worker-node invoke methods.

Tech Stack: ClojureScript, babashka.cli dispatch table, existing logseq.cli.command.* entry model, existing formatter/completion/test stack.

Related:

• /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs
• /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/core.cljs
• /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/list.cljs
• /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs
• /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/remove.cljs
• /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/query.cljs
• /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/search.cljs
• /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/show.cljs
• /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/completion_generator.cljs
• /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs
• /Users/rcmerci/gh-repos/logseq/src/main/frontend/worker/db_worker_node.cljs
• /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs
• /Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/completion_generator_test.cljs
• /Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_inventory.edn
• /Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn
• /Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md

Problem statement

Today users can see examples only via --help on each specific command entry.

That creates two UX gaps:

1. There is no dedicated way to request examples directly by command path.
2. There is no single command namespace for future automation/docs workflows that want examples on demand.

We need example as a first-class command group that resolves an existing command path and prints curated example lines.

Current baseline

• Command registration is centralized in src/main/logseq/cli/commands.cljs with a single dispatch table built from command/* namespaces.
• Command help rendering already supports per-entry :examples metadata through logseq.cli.command.core/command-summary.
• Graph Inspect and Edit currently includes top-level commands:
  • list
  • upsert
  • remove
  • query
  • search
  • show
• db-worker-node is an HTTP invoke daemon with no concept of CLI examples; this feature does not require worker protocol changes.

Phase 1 target coverage (Graph Inspect and Edit)

Phase 1 must support logseq example <target...> for all of these command paths:

Group	Target command path
list	list page, list tag, list property
upsert	upsert block, upsert page, upsert tag, upsert property
remove	remove block, remove page, remove tag, remove property
query	query, query list
search	search block, search page, search property, search tag
show	show

Additionally, phase 1 supports group-level prefix selectors for covered groups (example list, example upsert, example remove, example query, example search, example show).

Target UX

Main usage

logseq example <command-or-prefix...>

Examples:

logseq example upsert page
logseq example upsert
logseq example show
logseq example search block

Selector semantics:

• Exact command path: example upsert page returns examples only for upsert page.
• Prefix command path: example upsert returns merged examples for all covered upsert * subcommands in a stable order.

Help behavior

• logseq example shows available phase-1 example selectors.
• logseq example <target...> --help shows command help for that example selector.
• logseq example upsert --help and logseq example upsert page --help are both valid.

Output behavior

• Human output: clear text block with selected target and example lines.
• JSON/EDN output (required): include machine-readable fields, at minimum:
  • selector (requested selector, e.g. "upsert" or "upsert page")
  • matched-commands (resolved command paths)
  • examples (flattened example lines)
  • message (human-readable summary string)

Design

1) Create an example command namespace

Add a new namespace, e.g. src/main/logseq/cli/command/example.cljs, responsible for:

• declaring phase-1 target selector (Graph Inspect and Edit only)
• generating mirrored example entries from existing command paths
• validating requested target path
• building non-worker action payloads
• executing as pure local logic

2) Mirror both exact paths and prefix selectors

Use generated entries like:

• exact: example upsert page, example show, example search block
• prefix: example upsert, example list, example remove, example query, example search

This keeps behavior aligned with existing dispatch/help/completion generation while also supporting grouped output (example upsert) without introducing ad-hoc free-form parsing.

3) Reuse :examples metadata as source of truth

For each supported target command entry:

• pull :examples from the original entry metadata
• for exact selectors, return only that entry's examples
• for prefix selectors, aggregate examples from all matched covered subcommands

If any matched target has missing/empty examples, return a clear CLI error (new code such as :missing-examples) so metadata coverage remains enforceable.

4) Ensure metadata completeness for phase-1 targets

Add/normalize :examples metadata on phase-1 target entries where missing (notably query list).

5) Integrate into central command table

In commands.cljs:

• build a base-table from existing command namespaces
• generate exact-selector and prefix-selector example entries from that base table
• create final table = base-table + example entries

Then wire command handling for example commands in:

• parse/finalize branch (if needed)
• build-action
• execute

No server ensure/invoke is needed for example actions.

6) Update top-level help groups

In command/core.cljs top-level summary groups, include example under Utilities so the command is visible in logseq --help.

7) Completion support

Because example commands are mirrored table entries, existing completion generation should include them automatically once table wiring is updated.

Testing plan (TDD)

1. Add failing parser/help tests in src/test/logseq/cli/commands_test.cljs:

   • example group help appears
   • exact selectors: example upsert page, example show, example search block
   • prefix selectors: example upsert, example list, example query
   • unknown/uncovered selector returns expected error

2. Add focused tests for new namespace (new test file):

   • entry generation from base table
   • phase-1 filtering only allows Graph Inspect and Edit targets
   • missing examples metadata handling

3. Extend completion tests in src/test/logseq/cli/completion_generator_test.cljs:

   • example group appears
   • mirrored example command functions are generated

4. Add format assertions for required structured output:

   • human output includes selector, matched commands, and example lines
   • json/edn include selector, matched-commands, examples, and message

5. Extend CLI e2e inventory/spec:

   • add example command scope and selectors
   • add non-sync cases for representative exact and prefix selectors (example show, example upsert page, example upsert, example search block)

6. Run focused and full checks:

   • bb dev:test -v logseq.cli.commands-test
   • bb dev:test -v logseq.cli.completion-generator-test
   • bb -f cli-e2e/bb.edn test --skip-build
   • bb dev:lint-and-test

File-by-file change map

File	Change
/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/example.cljs	New namespace: target filtering, mirrored entries, build/execute helpers.
/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/commands.cljs	Build base table, append generated example entries, wire build/execute for example actions.
/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/core.cljs	Add example to top-level help groups (Utilities).
/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/query.cljs	Add missing :examples metadata for query list (if absent).
/Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/format.cljs	Add explicit example formatting branch for human and structured (json/edn) output contract.
/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/commands_test.cljs	Add parse/help/build/execute coverage for example commands.
/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/command/example_test.cljs	New unit tests for entry generation and target validation.
/Users/rcmerci/gh-repos/logseq/src/test/logseq/cli/completion_generator_test.cljs	Assert completion output includes example command tree.
/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_inventory.edn	Add example command inventory coverage.
/Users/rcmerci/gh-repos/logseq/cli-e2e/spec/non_sync_cases.edn	Add non-sync runtime cases for representative example commands.
/Users/rcmerci/gh-repos/logseq/docs/cli/logseq-cli.md	Document example command usage and phase-1 coverage.

db-worker-node impact

No db-worker-node API, transport, or thread-api changes are required in phase 1.

example is resolved and rendered entirely in CLI command metadata/action flow.

Rollout / extension plan

• Phase 1 (this plan): only Graph Inspect and Edit coverage.
• Phase 2: extend target selector to include Graph Management, Authentication, and Utilities commands.
• Keep coverage policy explicit in tests so newly added CLI commands either:
  • automatically receive example coverage, or
  • are intentionally excluded with a documented reason.

Open questions

1. For commands with sensitive placeholders, should we define a metadata convention to mark examples as redacted/non-runnable?