CLI Reference

This page provides detailed reference documentation for all CLI commands in Logseq Doctor.

Commands

backlog

Aggregate tasks from multiple pages into a unified backlog.

Usage:

Bash

lqd backlog [partial page names]

Description:

This command aggregates tasks from one or more pages into a unified backlog page. It reads configuration from a "backlog" page in your graph, where each line with page references or tags defines a separate backlog.

Features:

• Automatic task aggregation: Queries tasks from specified pages using the Logseq API
• Smart categorization: Organizes tasks into sections (Focus, Overdue, New tasks, Scheduled)
• Concurrent processing: Processes multiple pages in parallel for better performance
• Obsolete task removal: Automatically removes tasks that no longer exist in source pages
• Pin support: Tasks marked with 📌 emoji are preserved and not removed
• Overdue detection: Identifies and highlights tasks past their deadline or scheduled date
• Focus page: Aggregates focus tasks from all backlogs into a central focus page
• Directives: Modify tasks directly from the backlog page (see below)

Directives:

Directives let you modify tasks without leaving the backlog page. Prepend a keyword to any block-ref line, then run lqd backlog - the directive is applied to the real task and the prefix is stripped automatically.

Syntax	Effect on the real task
CANCELED ((uuid))	Sets status to CANCELED, adds cancelled:: [[date]] property, removes from backlog
WAITING ((uuid))	Sets status to WAITING
TODO ((uuid))	Resets status to TODO (useful to revert a DOING or WAITING task)
[#A] ((uuid))	Sets priority to A (High)
[#B] ((uuid))	Sets priority to B (Medium)
[#C] ((uuid))	Sets priority to C (Low)

Multiple directives can be combined on the same block ref by prepending them in sequence:

Markdown

- WAITING [#B] ((uuid))

This sets the task to WAITING and priority B in a single run. Directives are processed left-to-right and all applied atomically (the task file is opened and saved once per UUID).

Example backlog page before running lqd backlog:

Markdown

- CANCELED ((a1b2c3d4-...))
- WAITING ((e5f6a7b8-...))
- TODO ((f0a1b2c3-...))
- [#A] ((c9d0e1f2-...))
- WAITING [#B] ((e5f6a7b8-...))

After running, the directives are applied and the lines revert to plain ((uuid)) refs (or are removed for CANCELED tasks).

If the task block has not yet been written to disk by Logseq, the command forces a UUID write-back via the HTTP API before applying the directive. If Logseq is not running, the directive is skipped with a warning and the prefix is left in place for the next run.

Deduplication:

When the same block ref ((uuid)) appears more than once on a backlog page, lqd backlog keeps only one copy and removes the rest. The rules for which copy survives:

1. Scheduled section wins: if the ref exists under the ⏰ Scheduled tasks divider, that copy is kept and any copy elsewhere (Unranked, regular area) is removed.
2. Triaged section wins: if the ref exists under the 🏷️ Triaged tasks divider, copies in the regular area are removed.
3. First occurrence wins: for all other areas, the first copy encountered top-to-bottom is kept; subsequent duplicates are removed.

This runs automatically on every lqd backlog call, so manually placing a ref in two sections (e.g. Unranked and a Future sub-group) will converge to a single canonical location on the next run.

Configuration:

Create a page named "backlog" with lines containing page references or tags. The first page reference determines the backlog page name, and all referenced pages/tags are used as input sources.

Example:

Bash

# Process all backlogs
lqd backlog

# Process only backlogs matching "work"
lqd backlog work

# Process multiple specific backlogs
lqd backlog computer house

Environment Variables:

This command uses the following environment variables: LOGSEQ_GRAPH_PATH, LOGSEQ_HOST_URL, and LOGSEQ_API_TOKEN.

completion

Generate shell completion scripts.

Usage (Go CLI):

Bash

lqd completion [bash|zsh|fish|powershell]

Description:

Generate autocompletion scripts for your shell. This enables tab completion for commands and options.

Examples:

Bash:

Bash

lqd completion bash > /etc/bash_completion.d/lqd

Zsh:

Bash

lqd completion zsh > "${fpath[1]}/_lqd"

Fish:

Bash

lqd completion fish > ~/.config/fish/completions/lqd.fish

PowerShell:

Bash

lqd completion powershell > lqd.ps1

content

Append raw Markdown content to your Logseq graph.

Usage:

Bash

lqd content [OPTIONS]

Description:

This command allows you to programmatically add content to your Logseq pages. It's useful for automation and scripting workflows where you want to append content to your knowledge base.

Example:

Bash

echo "- New note" | lqd content

md

Add Markdown content to Logseq using the DOM.

Usage:

Bash

lqd md [OPTIONS]

Description:

This command reads Markdown content from stdin and adds it to your Logseq graph by parsing and manipulating the document object model (DOM). Unlike the content command which appends raw text, md parses the Markdown structure and properly integrates it into Logseq's outline format.

If --key is provided, the command searches for an existing block containing that key (case-insensitive) and updates it while preserving children, properties, and logbook entries. Otherwise, it creates a new block.

Features:

• Markdown parsing: Parses input as Markdown and converts it to Logseq's block structure
• Key-based updates: Use --key to search for and update existing blocks (case-insensitive)
• Parent block support: Can add content as a child of a specific block using --parent
• Page targeting: Supports adding to specific pages with --page
• Journal targeting: Supports adding to specific journal dates with --journal
• Multi-line content: Handles complex Markdown including tasks with properties and logbooks
• Smart placement: Adds to journal page by default, or under a parent block if specified
• Preserve structure: When updating blocks, preserves children, properties, and logbook entries

Flags:

Text Only

-j, --journal YYYY-MM-DD    Journal date (default: today)
-p, --page NAME             Page name to add the content to
   --parent TEXT            Partial text of a block to use as parent
-k, --key TEXT              Unique key to search for existing block

Examples:

Bash

# Add a simple note to today's journal
echo "New task" | lqd md

# Add content to a specific page
echo "Meeting notes" | lqd md --page "Work"

# Add content under a specific parent block
echo "Child task" | lqd md --parent "Project A"

# Add to a specific journal date
echo "Meeting notes" | lqd md --journal 2024-12-25

# Update an existing block by key (preserves children and properties)
echo "Updated content" | lqd md --key "unique identifier"

# Update a block on a specific page
echo "Update work item" | lqd md --page "Projects" --key "feature-123"

# Add a task with properties and logbook
echo "DOING Some task
collapsed:: true
:LOGBOOK:
CLOCK: [2025-08-27 Wed 21:12:50]
:END:" | lqd md --parent "work"

outline

Convert flat Markdown files to Logseq's bullet outline format.

Usage:

Bash

lqd outline [file ...] [flags]

Description:

Converts flat Markdown to Logseq's indented bullet outline. With no file arguments, reads from stdin. With files, writes to stdout by default. Ordered lists are converted to Logseq's native ordered list format (logseq.order-list-type:: number property). The conversion is idempotent.

Flags:

Text Only

-i, --in-place         Overwrite each file with its converted output
    --keep-breaks      Preserve blank lines as empty bullet lines
    --move-to string   Write converted output to this directory; remove original

Notes:

• --in-place and --move-to are mutually exclusive
• --move-to fails if the destination file already exists (never overwrites)

Examples:

Bash

# Stdin to stdout
printf '# Header\n\nParagraph.\n' | lqd outline

# Single file to stdout
lqd outline notes.md

# Edit in place
lqd outline --in-place notes.md

# Move converted file to Logseq graph directory
lqd outline --move-to ~/logseq/pages notes.md

# Preserve blank lines as empty bullet lines
lqd outline --keep-breaks notes.md

task

Manage tasks in your Logseq graph.

Usage:

Bash

lqd task [subcommand]

Description:

Parent command for task management operations. Use subcommands to add, list, or modify tasks in your Logseq graph.

Subcommands:

task ls

List tasks from your Logseq graph via the HTTP API.

Usage:

Bash

lqd task ls [tag...] [flags]

Description:

Queries tasks from your running Logseq instance. Positional arguments filter by tag or page reference (combined with OR). By default only active tasks (TODO, DOING, WAITING) are shown.

Flags:

Text Only

    --canceled    Include CANCELED tasks
-c, --completed   Include canceled and done tasks (shorthand for --canceled --done)
    --done        Include DONE tasks
    --json        Output raw JSON
-v, --verbose     Print the Datalog query before results

Environment Variables: LOGSEQ_HOST_URL, LOGSEQ_API_TOKEN

Examples:

Bash

# All active tasks
lqd task ls

# Filter by tag
lqd task ls work

# Include completed tasks
lqd task ls --completed

# JSON output for scripting
lqd task ls --json

task add

Add a new task to Logseq or update an existing one.

Usage:

Bash

lqd task add [task description] [OPTIONS]

Description:

Adds a new TODO task to your Logseq graph. By default, tasks are added to today's journal page. You can specify a different target using flags.

Features:

• Key-based updates: Use --key to search for and update existing tasks (case-insensitive)
• Flexible targeting: Add to journal pages, regular pages, or under specific blocks
• Smart search: When using --key, searches within the specified page/journal or block scope
• Preserve structure: When updating tasks, preserves children, properties, and logbook entries

Flags:

Text Only

-j, --journal YYYY-MM-DD    Journal date (default: today)
-p, --page NAME             Page name to add the task to
   --parent TEXT            Partial text of a block to use as parent
-k, --key TEXT              Unique key to search for existing task

Examples:

Bash

# Add a task to today's journal
lqd task add "Review pull request"

# Add a task to a specific page
lqd task add "Call client" --page "Work"

# Add a task to a specific journal date
lqd task add "Buy groceries" --journal 2024-12-25

# Update an existing task by key (preserves children and properties)
lqd task add "Water plants in living room" --key "water plants"

# Add a task under a specific block
lqd task add "Meeting notes" --parent "Project A"

# Update a task within a specific block scope
lqd task add "Updated task name" --parent "Project A" --key "task"

dashboard

Start PocketBase and the backlog web UI.

Usage:

Bash

lqd dashboard [OPTIONS]
lqd dash [OPTIONS]        # short alias

Description:

Starts PocketBase as a managed subprocess, waits for it to be ready, then serves the backlog dashboard at http://localhost:8091. On macOS the browser opens automatically.

The dashboard lets you browse, filter, sort, and reorder tasks across all your backlogs in a visual web UI. Rank changes are written directly to PocketBase; use lqd backlog to propagate them back to Logseq .md files.

Options:

Flag	Env var	Default	Description
-p, --port	LQD_SERVE_PORT	8091	HTTP server port

Required environment variables:

Variable	Description
POCKETBASE_URL	PocketBase base URL (default http://127.0.0.1:8090)
POCKETBASE_USERNAME	PocketBase admin email
POCKETBASE_PASSWORD	PocketBase admin password
LOGSEQ_GRAPH_PATH	Path to Logseq graph root (required for write-back operations)

Example:

Bash

# Start with defaults (port 8091)
lqd dashboard

# Start on a custom port
lqd dash --port 9000

# Start with explicit credentials
POCKETBASE_USERNAME=admin@example.com POCKETBASE_PASSWORD=secret lqd dashboard

See Dashboard Guide for a full walkthrough of the web UI.

---

tidy-up

Clean up and standardize your Markdown files.

Usage:

Bash

lqd tidy-up [OPTIONS] [FILES...]

Description:

This command helps ensure your Markdown files follow consistent formatting rules. It performs various cleanup operations:

• Removes double spaces (except in tables)
• Removes empty bullets
• Removes unnecessary brackets from tags
• Standardizes formatting

Example:

Bash

lqd tidy-up /path/to/markdown/files/*.md

Global Flags

Text Only

-h, --help

Show help information for any command.

Environment Variables

LOGSEQ_GRAPH_PATH

Path to your Logseq graph directory. Used by the backlog command to locate your graph.

Example:

Bash

export LOGSEQ_GRAPH_PATH=~/logseq/my-graph
lqd backlog

LOGSEQ_HOST_URL

Logseq API host URL. Used by the backlog command to connect to the Logseq API.

Default: http://localhost:12315

Example:

Bash

export LOGSEQ_HOST_URL=http://localhost:12315
lqd backlog

LOGSEQ_API_TOKEN

Logseq API authentication token. Required by the backlog command to authenticate with the Logseq API.

Example:

Bash

export LOGSEQ_API_TOKEN=your-api-token-here
lqd backlog

Exit Code

The CLI uses standard exit codes:

• 0: Success
• 1: General error
• 2: Command-line usage error

Tips

Combining Commands

You can combine multiple commands using shell pipes and scripting:

Text Only

```bash
# Example: Tidy up all Markdown files in a directory
find ~/notes -name "*.md" -exec lqd tidy-up {} \;
```

Automation

Use the Go CLI (lqd) in scripts and automation workflows for better performance:

Text Only

```bash
#!/bin/bash
# Daily note automation
echo "- $(date): Daily standup notes" | lqd content
```

Shell Aliases

Create shell aliases for frequently used commands:

Text Only

```bash
# Add to ~/.bashrc or ~/.zshrc
alias lqd-tasks='lqd task ls'
alias lqd-tidy='lqd tidy-up'
```