logseq/docs/agent-guide/080-logseq-cli-status-option-cleanup.md

Logseq CLI Status Option Cleanup Implementation Plan

Goal: align task-related CLI semantics by removing --status from upsert block, adding consistent -c aliases for all --content options, and improving invalid --status error output to include all available values.

Architecture: keep the current logseq-cli -> command parse/build -> transport/invoke -> db-worker-node thread-api flow, but move --status invalid-value reporting to runtime validation so it can use graph data.

Architecture: add a small db-worker-node read endpoint for task status values from the current graph, and reuse it in CLI command validation/error messaging.

Tech Stack: ClojureScript, babashka.cli, existing command modules under src/main/logseq/cli/command/*, formatter/error layer in src/main/logseq/cli/format.cljs.

Related: builds on docs/agent-guide/078-logseq-cli-task-subcommands.md and current command contracts in docs/cli/logseq-cli.md.

Problem statement

Current upsert block still accepts --status, even though task semantics are already represented by upsert task.

Current --content aliasing is inconsistent: search/upsert already support -c, but list task --content does not.

Current invalid enum error output for --status does not list accepted values, which slows down CLI troubleshooting.

Example current output:

logseq list task --status xxx
Error (invalid-options): Invalid value for option :status: xxx

Target UX should include available values in the error output.

Current baseline from implementation

1) upsert block --status is currently part of command spec and update path

src/main/logseq/cli/command/upsert.cljs currently includes :status inside upsert-block-spec and examples include upsert block --id 123 --status done.

upsert block update mode currently delegates to src/main/logseq/cli/command/update.cljs, where :status is parsed/normalized and merged into :update-properties as :logseq.property/status.

2) --content aliasing is partly consistent

Current :content options with :alias :c exist in:

• src/main/logseq/cli/command/search.cljs
• src/main/logseq/cli/command/upsert.cljs (upsert block, upsert task)

Current list task in src/main/logseq/cli/command/list.cljs defines :content without alias.

3) Invalid status message is parser-driven today, which blocks graph-derived values

src/main/logseq/cli/command/list.cljs and src/main/logseq/cli/command/upsert.cljs currently define :status with static :validate #{...} sets.

That causes invalid status values to fail at parse time, before repo/graph resolution and before any db query can run.

With parse-time rejection, CLI cannot include values from the current graph.

4) db-worker-node currently has no task-status-values endpoint

src/main/logseq/cli/common/db_worker.cljs currently supports task listing/filtering, but does not expose a dedicated API to list available task status values from graph data.

To satisfy the new requirement, we need a small read-only thread-api for status values and wire it through src/main/frontend/worker/db_core.cljs.

Scope

In scope:

1. Remove --status from upsert block option surface and help/examples.
2. Ensure every CLI --content option has -c alias.
3. When --status is invalid (e.g. list task --status xxx), show accepted values queried from the current graph in the error message.

Out of scope:

• New task query/filter semantics in db-worker.
• Changing task storage/property schema.
• New command groups beyond existing upsert task / list task.

Design decisions

Decision A: Task status writes move fully to upsert task

upsert block will no longer expose --status.

Task status changes should go through upsert task --id|--uuid|--page|--content ... --status ....

This removes overlap between generic block updates and task-specific semantics.

Decision B: Keep -c as the standard short alias for --content

Add :alias :c to any remaining :content specs missing it (currently list task).

No new short alias should be introduced for content.

Decision C: Validate --status against graph-derived values at runtime

For list task / upsert task status validation, use values queried from the current graph instead of static hardcoded sets in command spec.

This requires moving status value validation out of parse-time :validate #{...} and into command build/execute phase where graph/repo is available.

Target output shape:

Error (invalid-options): Invalid value for option :status: xxx. Available values (from current graph): todo, doing, done

(Exact values come from the active graph query result; ordering should be deterministic, e.g. sorted by status title.)

Proposed implementation plan

1. Add RED parser tests for upsert block --status to assert it becomes invalid (unknown option path).
2. Add RED parser tests for list task -c <text> to assert -c works as alias for --content.
3. Add RED command tests asserting invalid task status errors include graph-derived available values in message text.
4. Remove :status from upsert-block-spec in src/main/logseq/cli/command/upsert.cljs.
5. Remove/adjust upsert block examples and help text that mention --status.
6. If needed, add migration guidance in src/main/logseq/cli/commands.cljs for upsert block --status (guide user to upsert task).
7. Add :alias :c to list-task-spec :content in src/main/logseq/cli/command/list.cljs.
8. Remove parse-time static :validate #{...} for task :status options where graph-derived validation is required (list task, upsert task).
9. Add db-worker helper in src/main/logseq/cli/common/db_worker.cljs to list available task status values from the current graph.
10. Expose the helper via new thread-api in src/main/frontend/worker/db_core.cljs.
11. In CLI command layer (list.cljs and upsert.cljs), fetch status values for current repo/graph and validate --status; on invalid input return :invalid-options with available-values suffix from graph query result.
12. Keep output ordering deterministic (e.g. sorted asc by display name/ident) so error text and tests remain stable.
13. Update completion tests and command docs to reflect final option surface.
14. Update CLI user docs in docs/cli/logseq-cli.md for upsert block, upsert task, list task -c, and graph-derived status validation behavior.
15. Update CLI e2e inventory/cases where upsert block --status is currently listed/covered.
16. Run focused tests, then run full lint/test checks.

Files expected to change

Primary implementation files:

• /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/upsert.cljs
• /Users/rcmerci/gh-repos/logseq/src/main/logseq/cli/command/list.cljs
• /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

Primary tests:

• /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/src/test/logseq/cli/format_test.cljs (only if formatted error snapshots/assertions are affected)

Docs and e2e metadata:

• /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 implement tests before behavior changes.

Unit / command tests

Add tests in commands_test.cljs for:

• upsert block --id 1 --status done returns :invalid-options (or unknown option mapped to invalid-options).
• list task -c alpha parses to :list-task with :content "alpha".
• invalid status errors for task commands include a graph-derived available-values suffix (using mocked thread-api responses).

Completion tests

Update completion_generator_test.cljs to assert list task offers -c along with --content.

Docs/e2e coverage checks

Ensure inventory and cases no longer advertise upsert block --status.

Add/update one case that validates status updates via upsert task path.

Verification commands

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

Risks and mitigations

Risk: users relying on upsert block --status scripts will break.

Mitigation: provide explicit migration guidance in parser error messaging and update docs clearly.

Risk: status values query may return empty or unexpected shapes for some graphs.

Mitigation: normalize db-worker response contract, sort deterministically, and provide a clear fallback suffix when no status values are found.

Risk: moving status validation from parse time to runtime may change where errors are raised.

Mitigation: add focused parser/build/execute tests for list task and upsert task to lock error codes/messages and avoid regressions on other options.

Acceptance criteria

1. upsert block help/spec no longer includes --status.
2. All CLI options named --content support -c.
3. logseq list task --status xxx shows invalid-value error plus a deterministic available-values list queried from the current graph.
4. Existing upsert task --status ... and list task --status ... happy paths remain green.
5. CLI docs and e2e inventory reflect the new surface.

Question

No blocking question.

---