Logseq CLI

Overview

概述

Use

logseq

to inspect and edit graph entities, run Datascript queries, and control graph/server lifecycle.

使用

logseq

来查看和编辑图谱实体、运行Datascript查询，以及控制图谱/服务器的生命周期。

Quick start

快速开始

Run
```
logseq --help
```
to see top-level commands and global flags.
Run
```
logseq <command> --help
```
to see command-specific options.
Use
```
--graph
```
to target a specific graph.
Omit
```
--output
```
for human output. Set
```
--output json
```
or
```
--output edn
```
only when machine-readable output is required.

运行
```
logseq --help
```
查看顶级命令和全局标志。
运行
```
logseq <command> --help
```
查看命令专属选项。
使用
```
--graph
```
指定目标图谱。
省略
```
--output
```
将输出人类可读格式。仅当需要机器可读输出时，设置
```
--output json
```
或
```
--output edn
```
。

Command groups (from

logseq --help

)

命令组（来自

logseq --help

）

Graph inspect/edit:
```
list page
```
,
```
list tag
```
,
```
list property
```

upsert block

,

upsert page

,

upsert tag

,

upsert property

remove block

,

remove page

,

remove tag

,

remove property

```
query
```
,
```
query list
```
,
```
show
```

Graph management:

graph list|create|switch|remove|validate|info|export|import

Server management:
```
server list|status|start|stop|restart
```
Diagnostics:
```
doctor
```

图谱查看/编辑：
```
list page
```
,
```
list tag
```
,
```
list property
```

upsert block

,

upsert page

,

upsert tag

,

upsert property

remove block

,

remove page

,

remove tag

,

remove property

```
query
```
,
```
query list
```
,
```
show
```

图谱管理：

graph list|create|switch|remove|validate|info|export|import

服务器管理：
```
server list|status|start|stop|restart
```
诊断：
```
doctor
```

Global options

全局选项

```
--config
```
Path to
```
cli.edn
```
(default
```
~/logseq/cli.edn
```
)
```
--graph
```
Graph name
```
--data-dir
```
Path to db-worker data dir (default
```
~/logseq/graphs
```
)
```
--timeout-ms
```
Request timeout in ms (default
```
10000
```
)
```
--output
```
Output format (
```
human
```
,
```
json
```
,
```
edn
```
)
```
--verbose
```
Enable verbose debug logging to stderr

```
--config
```
```
cli.edn
```
的路径（默认
```
~/logseq/cli.edn
```
）
```
--graph
```
图谱名称
```
--data-dir
```
db-worker数据目录的路径（默认
```
~/logseq/graphs
```
）
```
--timeout-ms
```
请求超时时间（毫秒，默认10000）
```
--output
```
输出格式（
```
human
```
,
```
json
```
,
```
edn
```
）
```
--verbose
```
启用详细调试日志输出到stderr

Command option policy

命令选项规则

Do not memorize or hardcode command options in this skill.
Before running any command, always check live options with:
```
logseq <command> --help
```
```
logseq <command> <subcommand> --help
```

不要在此技能中记忆或硬编码命令选项。
在运行任何命令前，务必通过以下方式查看实时选项：
```
logseq <command> --help
```
```
logseq <command> <subcommand> --help
```

Example prerequisites

示例前置条件

Replace placeholder ids/uuids in examples (
```
123
```
,
```
321
```
,
```
1111...
```
) with real entities from the target graph.

Use

logseq list ...

,

logseq show ...

, or

logseq query ...

first to discover valid ids/uuids.

```
logseq graph export
```
requires
```
--file
```
; keep
```
graph import --input
```
consistent with the export path.

将示例中的占位符ID/UUID（如
```
123
```
,
```
321
```
,
```
1111...
```
）替换为目标图谱中的真实实体。

先使用

logseq list ...

,

logseq show ...

或

logseq query ...

发现有效的ID/UUID。

```
logseq graph export
```
需要
```
--file
```
参数；
```
graph import --input
```
需与导出路径保持一致。

Examples

示例

bash

undefined

bash

undefined

List pages (human output by default)

logseq list page --graph "my-graph" --limit 50 --sort updated-at --order desc

Include built-in tags/properties

logseq list tag --graph "my-graph" --include-built-in --limit 20 --output json logseq list property --graph "my-graph" --include-built-in --limit 20 --output json

Query by built-in query name

logseq query --graph "my-graph" --name "recent-updated" --inputs "[30]"

Query with ad-hoc Datascript EDN

logseq query --graph "my-graph" --query "[:find [?p ...] :where [?p :block/name]]"

List available queries (built-ins + custom-queries from cli.edn)

logseq query list --graph "my-graph" --output edn

Show a page tree or a block

logseq show --graph "my-graph" --page "Meeting Notes" --level 2 logseq show --graph "my-graph" --id 123 logseq show --graph "my-graph" --id "[123,456,789]"

Upsert a page (create or update by --id)

logseq upsert page --graph "my-graph" --page "Project X" logseq upsert page --graph "my-graph" --id 999 --update-properties "{:logseq.property/description "Example"}"

Upsert blocks

logseq upsert block --graph "my-graph" --target-page "Meeting Notes" --content "Discuss roadmap" logseq upsert block --graph "my-graph" --target-page "Meeting Notes" --content "AI summary of the discussion" --update-tags '["AI-GENERATED"]' logseq upsert block --graph "my-graph" --blocks "[{:block/title "A"} {:block/title "B"}]" logseq upsert block --graph "my-graph" --id 123 --update-tags '["AI-GENERATED"]' logseq upsert block --graph "my-graph" --id 123 --status done

Ensure a tag exists before associating it with a block

logseq upsert tag --graph "my-graph" --name "AI-GENERATED" logseq upsert block --graph "my-graph" --target-page "Meeting Notes" --content "AI summary of the discussion" --update-tags '["AI-GENERATED"]'

Upsert tag/property

logseq upsert tag --graph "my-graph" --name "Project" logseq upsert tag --graph "my-graph" --id 200 --name "Project Renamed" logseq upsert property --graph "my-graph" --name "Effort" --type number --cardinality one logseq upsert property --graph "my-graph" --id 321 --hide true

Remove entities

logseq remove block --graph "my-graph" --id "[123,456]" logseq remove block --graph "my-graph" --uuid "11111111-1111-1111-1111-111111111111" logseq remove page --graph "my-graph" --name "Old Page" logseq remove tag --graph "my-graph" --name "Old Tag" logseq remove property --graph "my-graph" --id 321

Graph and server commands

logseq graph create --graph "my-graph" logseq graph list logseq graph switch --graph "my-graph" logseq graph info --graph "my-graph" logseq graph export --graph "my-graph" --type edn --file /tmp/my-graph.edn logseq graph import --graph "my-graph-import" --type edn --input /tmp/my-graph.edn logseq server status --graph "my-graph" logseq doctor

undefined

logseq graph create --graph "my-graph" logseq graph list logseq graph switch --graph "my-graph" logseq graph info --graph "my-graph" logseq graph export --graph "my-graph" --type edn --file /tmp/my-graph.edn logseq graph import --graph "my-graph-import" --type edn --input /tmp/my-graph.edn logseq server status --graph "my-graph" logseq doctor

undefined

Tag association semantics

标签关联语义

For block or page tag association, prefer explicit CLI tag options such as
```
--update-tags
```
and
```
--remove-tags
```
.
Do not treat writing
```
#TagName
```
inside
```
--content
```
as equivalent guidance to explicit tag association.
```
upsert block
```
supports
```
--update-tags
```
in both create mode and update mode.
```
--update-tags
```
expects an EDN vector.
Tag values may be tag title/name strings, db/id, UUID, or
```
:db/ident
```
values.
String tag values may include a leading
```
#
```
, but they should still be passed inside
```
--update-tags
```
rather than embedded in content as a substitute for association.
If the user asks to tag a block or page, prefer explicit tag association over embedding hashtags in content.
Tags must already exist and be public. If needed, create the tag first with
```
upsert tag --name "<TagName>"
```
.

对于块或页面的标签关联，优先使用明确的CLI标签选项，如
```
--update-tags
```
和
```
--remove-tags
```
。
不要将在
```
--content
```
中写入
```
#TagName
```
视为与明确标签关联等效的指引。
```
upsert block
```
在创建模式和更新模式下均支持
```
--update-tags
```
。
```
--update-tags
```
期望接收一个EDN向量。
标签值可以是标签标题/名称字符串、db/id、UUID或
```
:db/ident
```
值。
字符串类型的标签值可以包含前缀
```
#
```
，但仍应通过
```
--update-tags
```
传递，而非嵌入到内容中作为关联的替代方式。
如果用户要求为块或页面添加标签，优先使用明确的标签关联，而非在内容中嵌入话题标签。
标签必须已存在且为公开状态。如有需要，先使用
```
upsert tag --name "<TagName>"
```
创建标签。

Pitfalls

注意事项

--content "Summary #AI-GENERATED"

is not the same guidance as

--update-tags '["AI-GENERATED"]'

.

Do not pass
```
--update-tags
```
as a comma-separated string. Use an EDN vector.
Do not assume a hashtag in block text will replace the need for explicit tag association when the user asks for a tagged block.
If tag association fails, verify the tag exists and is public before retrying.

--content "Summary #AI-GENERATED"

与

--update-tags '["AI-GENERATED"]'

的作用并不相同。

不要将
```
--update-tags
```
作为逗号分隔的字符串传递，应使用EDN向量。
当用户要求添加标签的块时，不要假设块文本中的话题标签可以替代明确的标签关联。
如果标签关联失败，请先验证标签是否存在且为公开状态，然后再重试。

Tips

提示

```
query list
```
returns both built-ins and
```
custom-queries
```
from
```
cli.edn
```
.
```
show --id
```
accepts either one db/id or an EDN vector of ids.
```
remove block --id
```
also accepts one db/id or an EDN vector.
```
upsert block
```
enters update mode when
```
--id
```
or
```
--uuid
```
is provided.
Always verify command flags with
```
logseq --help
```
and
```
logseq <...> --help
```
before execution.
If
```
logseq
```
reports that it doesn’t have read/write permission for data-dir, then add read/write permission for data-dir in the agent’s config.
In sandboxed environments,
```
graph create
```
may print a process-scan warning to stderr; if command status is
```
ok
```
, the graph is still created.

```
query list
```
返回内置查询和
```
cli.edn
```
中的
```
custom-queries
```
。
```
show --id
```
支持单个db/id或EDN格式的ID向量。
```
remove block --id
```
也支持单个db/id或EDN格式的ID向量。
当提供
```
--id
```
或
```
--uuid
```
时，
```
upsert block
```
进入更新模式。
执行命令前务必通过
```
logseq --help
```
和
```
logseq <...> --help
```
验证命令标志。
如果
```
logseq
```
报告没有数据目录的读写权限，在agent配置中为数据目录添加读写权限。
在沙箱环境中，
```
graph create
```
可能会向stderr打印进程扫描警告；如果命令状态为
```
ok
```
，则图谱已成功创建。

References

参考资料

Built-in tags and properties: See
```
references/logseq-builtins.md
```
when you need canonical built-ins for
```
list ... --include-built-in
```
or for tag/property upsert fields.

内置标签和属性：当需要
```
list ... --include-built-in
```
的标准内置项或标签/属性更新字段时，请查看
```
references/logseq-builtins.md
```
。

logseq-cli

Original

Translation

Logseq CLI

Logseq CLI

Overview

概述

Quick start

快速开始

Command groups (from logseq --help)

命令组（来自logseq --help）

Global options

全局选项

Command option policy

命令选项规则

Example prerequisites

示例前置条件

Examples

示例

List pages (human output by default)

List pages (human output by default)

Include built-in tags/properties

Include built-in tags/properties

Query by built-in query name

Query by built-in query name

Query with ad-hoc Datascript EDN

Query with ad-hoc Datascript EDN

List available queries (built-ins + custom-queries from cli.edn)

List available queries (built-ins + custom-queries from cli.edn)

Show a page tree or a block

Show a page tree or a block

Upsert a page (create or update by --id)

Upsert a page (create or update by --id)

Upsert blocks

Upsert blocks

Ensure a tag exists before associating it with a block

Ensure a tag exists before associating it with a block

Upsert tag/property

Upsert tag/property

Remove entities

Remove entities

Graph and server commands

Graph and server commands

Tag association semantics

标签关联语义

Pitfalls

注意事项

Tips

提示

References

参考资料

Command groups (from
`logseq --help`
)

命令组（来自
`logseq --help`
）