logseq/docs/agent-guide/027-logseq-cli-update-command.md

# Logseq CLI Update Command (Move Refactor)

## Summary
Introduce a new `update` CLI command that subsumes the current `move` command and adds tag/property updates. The new command keeps all existing move capabilities/options, makes move targets optional (no target means no move), and adds update/remove semantics for tags and properties. The plan is grounded in current `logseq-cli` parsing/execution and db-worker-node outliner ops.

## Goals
- Replace `move` command behavior with `update` while keeping all current move options and semantics.
- Allow `update` to move blocks *and/or* update tags/properties in one command.
- Support new options:
  - `--update-tags`, `--update-properties`
  - `--remove-tags`, `--remove-properties`
- Reuse tag/property parsing and resolution rules from `add block`:
  - Identifiers accept `db/id`, `db/ident`, `block/title`.
  - `--update-tags` and `--update-properties` accept the same EDN format as `add block` `--tags`/`--properties`.
  - `--remove-tags` and `--remove-properties` accept EDN vectors of tag/property identifiers.

## Non-goals
- Changing db-worker-node APIs or introducing new outliner ops.
- Expanding `update` beyond blocks (no page-level update scope in this iteration).
- Changing move semantics or target resolution.

## Background: Current Move Command
- CLI move implementation lives in `src/main/logseq/cli/command/move.cljs`.
- It requires a source (`--id` or `--uuid`) and a target (`--target-id`, `--target-uuid`, or `--target-page`).
- Execution uses `:thread-api/apply-outliner-ops` with `[:move-blocks ...]`.
- Move output formatting in `src/main/logseq/cli/format.cljs` uses `format-move-block`.

## Proposed Behavior (Update Command)
### Required/Optional Inputs
- **Source is required**: one of `--id` or `--uuid`.
- **Move targets are optional**:
  - `--target-page`, `--target-uuid`, `--target-id`, `--pos` are optional.
  - If no target is provided, no move occurs and the command only updates tags/properties.
  - If a target is provided, move executes with the same semantics as today.
- **Update/remove options are optional**:
  - `--update-tags` (EDN vector, same as `add block --tags`)
  - `--update-properties` (EDN map, same as `add block --properties`)
  - `--remove-tags` (EDN vector of tag identifiers)
  - `--remove-properties` (EDN vector of property identifiers)

### Validation Rules
- Only one source selector is allowed: `--id` or `--uuid`.
- Only one target selector is allowed: `--target-id`, `--target-uuid`, or `--target-page`.
- `--pos sibling` is only valid when the target is a block (not a page), same as `move`.
- At least one of the following must be provided: target (move) or update/remove options.
- `--update-tags` and `--update-properties` accept the same EDN grammar and validations as in `add`.
- `--remove-tags` and `--remove-properties` must be non-empty vectors (EDN), with identifiers validated similarly to add.

### Execution Semantics
- Resolve source block to `db/id` using existing move helpers.
- If move target provided, resolve target entity using existing move helpers and compute `pos` opts.
- Tag/property updates use current outliner ops (no new db-worker changes):
  - **Add/update tags**: `[:batch-set-property [block-ids :block/tags tag-id {}]]` for each tag.
  - **Add/update properties**: `[:batch-set-property [block-ids property-id value {}]]`.
  - **Remove tags**: `[:batch-delete-property-value [block-ids :block/tags tag-id]]`.
  - **Remove properties**: `[:batch-remove-property [block-ids property-id]]`, with property resolution aligned to `add` (built-in/public property rules).
- Combine operations into a single `apply-outliner-ops` call when possible to keep updates atomic and reduce roundtrips.

## Design and Implementation Plan
### 1) Create `update` command module
- New file: `src/main/logseq/cli/command/update.cljs`.
- Start from `move.cljs` and expand the spec to include update/remove tag/property options.
- Extract shared helpers from `move.cljs` (e.g., `resolve-source`, `resolve-target`, `pos->opts`, `invalid-options?`) into a small shared namespace or move into `update.cljs`.

### 2) Reuse tag/property parsing and resolution from `add`
- Refactor `src/main/logseq/cli/command/add.cljs` to expose reusable helpers for:
  - `parse-tags-option`, `parse-properties-option` (for update)
  - `resolve-tags`, `resolve-properties` (for update)
  - Tag/property identifier normalization functions if needed for remove vectors
- Keep the parsing behavior exactly consistent with `add block`.
- Add new helper in `add` (or a shared namespace) to parse **remove vectors**:
  - `parse-tags-vector-option` (vector of tag identifiers)
  - `parse-properties-vector-option` (vector of property identifiers)

### 3) Update top-level command registry
- Add `update` to `src/main/logseq/cli/commands.cljs` table and summary groups.
- Remove `move` from the command registry and help output (no alias/compat).

### 4) Update parse/validation logic
- In `finalize-command` (`src/main/logseq/cli/commands.cljs`):
  - Add `update`-specific validation for sources, targets, and update/remove options.
  - Reuse `update-command/invalid-options?`.
  - Allow missing target when update/remove options are present.
  - Keep error messaging aligned with existing CLI patterns.

### 5) Implement update action building
- `build-action` returns a combined action with:
  - `:type :update-block`
  - `:id`/`:uuid` for source, optional target selectors, `:pos` default `first-child` when move is requested
  - `:update-tags`, `:update-properties`, `:remove-tags`, `:remove-properties`
- `execute-update`:
  - Resolve source; resolve target only when move is requested.
  - Build a vector of outliner ops, in order: move (if present), then remove tags/properties, then update/add tags/properties (order can be adjusted if needed for predictable results).
  - Use `:thread-api/apply-outliner-ops` once with all ops.

### 6) Update output formatting
- `src/main/logseq/cli/format.cljs`:
  - Add `format-update-block` to describe move + updates in a concise line.
  - Update dispatcher to handle `:update-block`.

### 7) Tests
- Unit tests in `src/test/logseq/cli/commands_test.cljs`:
  - Parsing: `update` accepts `--id/--uuid`, optional target, and new options.
  - Validation: missing source, invalid target selector combinations, invalid pos, invalid EDN options.
  - Ensure that `update` without target but with update/remove options is accepted.
- Format tests in `src/test/logseq/cli/format_test.cljs` for `:update-block`.
- Integration tests in `src/test/logseq/cli/integration_test.cljs`:
  - Move-only update should behave the same as current `move`.
  - Update tags/properties on an existing block.
  - Remove tags/properties and validate via `show` or query.

## Open Questions
- If only `--pos` is provided without any target selector, return the error: `--pos is only valid when a target is provided`.

## Risks / Edge Cases
- If tag/property parsing rules diverge from `add`, user experience becomes inconsistent. Refactor shared parsing to avoid drift.
- Combining move and property updates in one `apply-outliner-ops` call needs to preserve correct operation order; keep move first unless property updates depend on position.
- Ensure non-page validation for source and block target remains intact when refactoring.

## Implementation Checklist (Concrete File Touches)
- Add: `src/main/logseq/cli/command/update.cljs`.
- Update: `src/main/logseq/cli/commands.cljs` (table, validation, action dispatch).
- Update: `src/main/logseq/cli/command/core.cljs` (top-level summary group list to include update).
- Update: `src/main/logseq/cli/format.cljs` (formatting for update).
- Update: `src/test/logseq/cli/commands_test.cljs`.
- Update: `src/test/logseq/cli/format_test.cljs`.
- Update: `src/test/logseq/cli/integration_test.cljs`.

## Verification
- Run unit tests: `bb dev:test -v logseq.cli.commands-test`.
- Run format tests: `bb dev:test -v logseq.cli.format-test`.
- Run CLI integration tests (move/update subset): `bb dev:test -v logseq.cli.integration-test`.
- Optional full suite: `bb dev:lint-and-test`.