A command-line interface to a Logseq graph over Logseq's local HTTP API, built for a caller that is a script or an AI agent rather than a person at a prompt.
Command: One operation the CLI performs, implemented as one decorated function. There are 37. Avoid: subcommand, verb, action
Command Name:
A string that invokes a Command. A Command usually has one, but may have
several — remove-block and delete-block reach the same Command. There are
38 names for 37 Commands.
Avoid: command alias, alias
Canonical Name:
The Command Name a Command is defined under, and the one the documentation
uses. remove-block is canonical; delete-block exists so that the most
common wrong guess works instead of erroring out.
Avoid: primary name, real name
Parameter Alias:
A second spelling of one option, accepted interchangeably. Every option taking
a page name accepts both --page and --name.
Avoid: alias, option alias, flag alias
Registry:
The set of Command Names Click resolves against, i.e. cli.commands. It is
the only authority on which Commands exist; the help text is a rendering of
it, not a second source.
Avoid: command list, command table
Page Alias: A Logseq alias — an alternative name under which a page can be addressed inside the graph. Unrelated to Command Name and Parameter Alias. Logseq's API does not resolve it; the CLI does, by the rule Logseq's UI follows (ADR 0002). Avoid: alias (unqualified)
Journal Page: The page Logseq keeps for one calendar day. Addressed by date, not by title. Avoid: daily note, diary entry
Block: One bullet in a page, with an identity of its own and possibly children. Avoid: node, item, entry
Id Line:
A line id:: <uuid> in a Block's text. Logseq reads it as the Block's uuid,
not as content, so whoever writes one decides which Block the uuid names.
Avoid: id property, uuid line
Reference:
A mention of another page or Block inside a Block's text: a Block Ref, a page
link [[name]] or a tag #name. Logseq records all three as the Block's refs.
Avoid: link (for the whole family)
Block Ref:
((uuid)) in a Block's text, standing for the Block with that uuid. The one
kind of Reference that points at a Block rather than a page.
Avoid: block reference link, embed
Task:
A Block Logseq reads as a task: one with a Marker. Text that only looks like
one — TODO:, a lower-case todo, TODO followed by a line break, a
Markdown checkbox — is not a Task.
Avoid: todo (for the Block), checkbox, to-do item
Marker:
The keyword at the start of a Task's text that states where it stands —
TODO, DOING, DONE and others. Logseq's parser fixes which keywords are
Markers; the graph's config only picks the ones new Tasks get.
Avoid: status keyword, workflow keyword
Task State:
Where a Task stands, read from its Marker as Logseq draws it: open (an empty
box for NOW, LATER, TODO, DOING, IN-PROGRESS, WAIT and WAITING;
STARTED, which Logseq parses but draws no box for, counts as open too), done (a ticked box:
DONE) or cancelled (no box, struck through: CANCELED, CANCELLED).
Cancelled is not done.
Avoid: status (unqualified), complete, closed
Refusal: The tool declining a call it will not perform — bad input, a missing page, an ambiguous match. Distinct from a failure: nothing broke, and no data was touched. Avoid: error, rejection
Note:
A line on stderr, starting Note:, that tells the caller something without
refusing: what the tool changed on the way, what it left out of the output, or
what Logseq will make of the text. A Refusal may still follow it.
Avoid: hint, info
Strict Insert:
The contract that a write either lands where it was asked to land or is
refused. It exists because Logseq answers some failed writes with HTTP 200 and
a null body, so a write is verified after the fact rather than trusted.
Avoid: safe write, verified write
Precondition:
What a caller says it read before it changes a Block: the Hash (or
Tree Hash) of the block, or for set-todo-status its marker. The write is
refused, with precondition_failed, unless the block is still what the caller
read. It guards the caller's decision across calls, which Strict Insert (was
my write stored) and the block_changed re-read (did the block change between
this command's own read and its write) do not: only the caller knows what it
read. [safety] require_preconditions makes a Precondition mandatory.
Avoid: lock, guard, version check
Hash:
A short digest of one Block's content, shown as hash by the read commands
with --json. It sees text, properties and the DONE lines of the logbook; it
ignores collapsing, id:: lines, clock lines and where the block stands, so
moving a block does not change it. Compared by value, never ordered.
Avoid: version, etag, checksum
Tree Hash:
The Hash of a Block together with everything under it, content and order
(tree_hash of get-block --json). The Precondition of remove-block, since
the hash of the block alone would not see a child added after the read. Also
the check before every removal of a block a command read: a removal cascades,
so the block is read again just before the delete and refused with
block_changed when its Tree Hash is another (copy-block --remove, which
compares with the state it copied, remove-block, and the page's property
block that remove-property removes with its last key).
Avoid: subtree hash, deep hash
Dry Run: A preview of a write that performs no write. Available on every Command that writes. Avoid: simulation, test mode