LogSeq CLI

A command-line interface for LogSeq operations via its HTTP API.

Zero dependencies — uses only Bun built-in APIs and native TypeScript.

Requirements

• Bun runtime
• LogSeq with HTTP API server enabled
• API token from LogSeq

Environment Variables

Variable	Required	Default	Description
LOGSEQ_API_TOKEN	Yes	-	Your LogSeq API token
LOGSEQ_HOST	No	127.0.0.1	LogSeq server host
LOGSEQ_PORT	No	12315	LogSeq server port
LOGSEQ_PROTOCOL	No	http	Protocol (http/https)

Installation

# Clone the repository
git clone <repository-url>
cd tools_for_logseq

# Install dependencies
bun install

# Set up environment variables
cp .env.template .env
# Edit .env and set LOGSEQ_API_TOKEN to your token

Getting Your API Token

1. Open Logseq
2. Go to Settings > Features
3. Enable "HTTP APIs Server"
4. Set your token in "Authorization tokens"
5. Copy that token to your .env file as LOGSEQ_API_TOKEN

Project Structure

tools_for_logseq/
├── logseq.ts              # CLI entry point
├── cli/
│   ├── arg_parser.ts      # Argument parsing utilities
│   ├── arg_parser.test.ts # Tests for argument parsing
│   ├── commands.ts        # Command implementations
│   └── help.ts            # Help text and documentation
├── logseq/
│   └── http_client.ts     # LogSeq HTTP API client library
├── package.json
└── README.md

Usage

bun run logseq <command> [options]

Commands

Page Commands

list-pages

List all pages in the graph.

# List pages (excluding journals)
bun run logseq list-pages

# Include journal pages
bun run logseq list-pages --include-journals

# Output as JSON
bun run logseq list-pages --format json

get-page

Get content of a specific page with metadata and blocks.

# Get page content
bun run logseq get-page "My Page"

# Output as JSON
bun run logseq get-page "My Page" --format json

# Alternative: use --name flag instead of positional argument
bun run logseq get-page --name "My Page"

create-page

Create a new page.

# Create empty page
bun run logseq create-page "New Page"

# Create page with initial content
bun run logseq create-page "New Page" --content "Initial content here"

# Alternative: use --title flag instead of positional argument
bun run logseq create-page --title "New Page" --content "Initial content here"

update-page

Update an existing page with new content and/or properties.

# Append content to a page
bun run logseq update-page "My Page" --content "Additional content"

# Update page properties
bun run logseq update-page "My Page" --properties '{"status": "done", "priority": "high"}'

# Update both content and properties
bun run logseq update-page "My Page" --content "More text" --properties '{"updated": true}'

# Alternative: use --name flag instead of positional argument
bun run logseq update-page --name "My Page" --content "Additional content"

delete-page

Delete a page (requires confirmation).

# Delete a page (requires --force flag)
bun run logseq delete-page "Old Page" --force

# Alternative: use --name flag instead of positional argument
bun run logseq delete-page --name "Old Page" --force

search

Search for content across the graph.

# Basic search
bun run logseq search "keyword"

# Limit results
bun run logseq search "keyword" --limit 50

# Exclude block content from results
bun run logseq search "keyword" --no-blocks

# Exclude page name matches
bun run logseq search "keyword" --no-pages

# Include file name matches
bun run logseq search "keyword" --include-files

# Output as JSON
bun run logseq search "keyword" --format json

# Combined options
bun run logseq search "keyword" --limit 100 --include-files --format json

# Alternative: use --query flag instead of positional argument
bun run logseq search --query "keyword" --limit 50

Block Commands

insert-block

Create a new block.

# Insert block into a page (as page-level block)
bun run logseq insert-block "Block content" --parent "My Page" --page-block

# Insert block as child of another block (by UUID)
bun run logseq insert-block "Child content" --parent "block-uuid-here"

# Insert block before the parent
bun run logseq insert-block "Content" --parent "block-uuid" --before

# Insert block with custom UUID
bun run logseq insert-block "Content" --parent "My Page" --page-block --uuid "custom-uuid-v4"

# Output as JSON (includes new block's UUID)
bun run logseq insert-block "Content" --parent "My Page" --page-block --format json

# Alternative: use --content flag instead of positional argument
bun run logseq insert-block --content "Block content" --parent "My Page" --page-block

edit-block

Enter block editing mode in LogSeq.

# Edit a block by UUID
bun run logseq edit-block "block-uuid-here"

# Edit with cursor at specific position
bun run logseq edit-block "block-uuid-here" --pos 10

# Alternative: use --uuid flag instead of positional argument
bun run logseq edit-block --uuid "block-uuid-here" --pos 10

exit-editing

Exit editing mode in LogSeq.

# Exit editing mode
bun run logseq exit-editing

# Exit but keep block selected
bun run logseq exit-editing --select

get-page-blocks

Get the block tree for a specific page.

# Get blocks as formatted text
bun run logseq get-page-blocks "My Page"

# Get blocks as JSON (includes UUIDs)
bun run logseq get-page-blocks "My Page" --format json

# Alternative: use --page flag instead of positional argument
bun run logseq get-page-blocks --page "My Page" --format json

Context Commands

get-all-pages

List all pages (with optional repository filter).

# Get all pages
bun run logseq get-all-pages

# Get pages from specific repository
bun run logseq get-all-pages --repo "my-repo"

# Output as JSON
bun run logseq get-all-pages --format json

get-current-page

Get the currently active page or block in LogSeq.

# Get current page/block
bun run logseq get-current-page

# Output as JSON
bun run logseq get-current-page --format json

get-current-blocks

Get the block tree of the currently active page.

# Get current page blocks
bun run logseq get-current-blocks

# Output as JSON
bun run logseq get-current-blocks --format json

get-editing-content

Get the content of the block currently being edited.

# Get editing block content
bun run logseq get-editing-content

# Output as JSON
bun run logseq get-editing-content --format json

Other

help

Show help information.

# Show general help
bun run logseq help

# Show help for specific command
bun run logseq help insert-block
bun run logseq help search

# Alternative help flags
bun run logseq --help
bun run logseq -h

Common Workflows

Create a page and add blocks

# Create a new page
bun run logseq create-page "Project Notes"

# Add blocks to it
bun run logseq insert-block "First item" --parent "Project Notes" --page-block
bun run logseq insert-block "Second item" --parent "Project Notes" --page-block

Get a block UUID and add child blocks

# Get blocks with UUIDs
bun run logseq get-page-blocks "My Page" --format json

# Use a UUID to add a child block
bun run logseq insert-block "Child content" --parent "returned-block-uuid"

Search and inspect results

# Search for content
bun run logseq search "meeting notes" --format json

# Get full content of a matching page
bun run logseq get-page "Weekly Meeting Notes"

Interactive editing workflow

# Get current context
bun run logseq get-current-page

# Get blocks on current page
bun run logseq get-current-blocks --format json

# Edit a specific block
bun run logseq edit-block "block-uuid"

# Check what's being edited
bun run logseq get-editing-content

# Exit editing mode
bun run logseq exit-editing

Compiling to a Single Binary

Bun can compile this CLI to a standalone executable that doesn't require Bun to be installed.

Basic compilation

bun build --compile logseq.ts --outfile logseq

With minification (smaller file size)

bun build --compile --minify logseq.ts --outfile logseq

Cross-compilation for other platforms

# Linux x64
bun build --compile --target=bun-linux-x64 logseq.ts --outfile logseq-linux

# macOS ARM (Apple Silicon)
bun build --compile --target=bun-darwin-arm64 logseq.ts --outfile logseq-mac-arm

# macOS x64 (Intel)
bun build --compile --target=bun-darwin-x64 logseq.ts --outfile logseq-mac-x64

# Windows x64
bun build --compile --target=bun-windows-x64 logseq.ts --outfile logseq.exe

Using the compiled binary

# Make executable (if needed)
chmod +x logseq

# Run commands
./logseq help
./logseq list-pages
./logseq get-page "My Page"

Installing system-wide

# Compile
bun build --compile --minify logseq.ts --outfile logseq

# Move to a directory in your PATH
sudo mv logseq /usr/local/bin/

# Now use from anywhere
logseq help
logseq list-pages

Output Formats

Most commands support --format option:

• text (default): Human-readable formatted output
• json: Machine-readable JSON output, useful for scripting and piping to tools like jq

Testing

Run the test suite with:

bun test

Error Handling

The CLI will exit with code 1 and display an error message when:

• Required arguments are missing
• Required environment variables are not set
• The LogSeq API returns an error
• A referenced page or block doesn't exist

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for guidelines, including information about:

• Development workflow
• Testing practices
• AI-assisted development
• Guidelines for AI coding assistants

License

MIT