Using Linkly AI CLI

Introduction to Linkly AI CLI

Linkly AI CLI is a command-line tool that connects to Linkly AI Desktop’s MCP service, allowing you to search, browse, and read local documents from the terminal. It also serves as a bridge between AI Agents (such as Claude Desktop, Cursor) and Linkly AI.

Terminal Search

Search your documents directly from the command line — ideal for developers and power users

MCP Bridge

Run in stdio MCP mode, enabling Claude Desktop, Cursor, and other AI tools to call Linkly AI

Installation

macOS / Linux
Windows
Cargo

Run in your terminal:

curl -sSL https://updater.linkly.ai/cli/install.sh | sh

Or install via Homebrew:

brew tap LinklyAI/tap
brew install linkly

Run in PowerShell:

irm https://updater.linkly.ai/cli/install.ps1 | iex

Install from crates.io (requires Rust toolchain):

cargo install linkly-ai-cli

After installation, verify the installation:

linkly --version

By default, the CLI discovers and connects to the local Linkly AI Desktop app via ~/.linkly/port. You can also connect to a remote device via LAN or the cloud tunnel — see Connection Modes below.

Usage

The CLI follows a search → grep or outline → read progressive workflow: first search to find target documents, then use grep to find patterns or view the outline to understand the structure, and finally read the specific content.

Check Connection Status

linkly status

Returns the running status, version number, number of indexed documents, and indexing status of Linkly AI Desktop.

Search Documents

linkly search "keywords or phrases"

Searches your local documents and returns the most relevant results, including title, path, relevance score, and content snippet. Common parameters:

# Limit the number of results (default 20, max 50)
linkly search "API design" --limit 5

# Filter by document type
linkly search "meeting minutes" --type pdf,docx

# Output in JSON format (suitable for scripting)
linkly search "budget report" --json

View Document Outline

linkly outline <DOC_ID>

Retrieves the structured outline and metadata of a document. DOC_ID is obtained from search results. You can view multiple documents at once:

linkly outline id1 id2 id3

The outline feature works best with Markdown and DOCX documents, as their heading structures can be parsed. For plain text or PDFs without bookmarks, it’s recommended to use the read command directly.

Search Patterns in Documents

linkly grep <PATTERN> <DOC_ID>

Search for regex pattern matches within a single document. Use when you need to find specific text (terms, names, dates, identifiers, etc.):

# Find a pattern in a document
linkly grep "useState" 456

# Case-insensitive with context lines
linkly grep "error|warning" 1044 -C 3 -i

# Count matches only
linkly grep "TODO" 591 --mode count

# Paginate matches (skip first 20, show next 20)
linkly grep "import" 302 --offset 20 --limit 20

Read Document Content

linkly read <DOC_ID>

Reads the full content of a document, outputting text with line numbers. For long documents, you can read in pages:

# Start from line 50, read 100 lines
linkly read <DOC_ID> --offset 50 --limit 100

Pagination strategy: By default, 200 lines are read per request (max 500 lines). For long documents, adjust --offset to read progressively:

linkly read <DOC_ID> --offset 1 --limit 200    # Lines 1-200
linkly read <DOC_ID> --offset 201 --limit 200  # Lines 201-400
linkly read <DOC_ID> --offset 401 --limit 200  # Lines 401-600

MCP Mode

linkly mcp

Runs as a stdio MCP server, exposing Linkly AI’s tools to MCP-compatible AI clients. Configure Claude Desktop and other local AI apps: Add the following to the configuration file of Claude Desktop or similar apps:

macOS / Linux
Windows

Edit ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "linkly-ai": {
      "command": "linkly",
      "args": ["mcp"]
    }
  }
}

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "linkly-ai": {
      "command": "linkly",
      "args": ["mcp"]
    }
  }
}

Configure Cursor: In Cursor, open Settings → MCP Servers → Add Server, and add:

Name: linkly-ai
Command: linkly mcp

Update CLI

linkly self-update

Automatically checks for and updates to the latest version. The CLI also checks for updates in the background on each launch and will prompt you to run this command if a new version is available.

Connection Modes

The CLI supports three ways to connect to your Linkly AI knowledge base:

Mode	Flags	How it works
Local	(default, no flags needed)	Auto-discovers the desktop app via `~/.linkly/port`
LAN	`--endpoint <url> --token <token>`	Direct connection to another device on the local network
Remote	`--remote`	Connects via `https://mcp.linkly.ai` cloud tunnel using API Key

Local Mode (default)

No extra flags needed. The CLI reads ~/.linkly/port to find the running desktop app:

linkly search "machine learning"
linkly status

LAN Mode

Connect to a Linkly AI instance running on another device in your local network. The token can be found in the desktop app under Settings → MCP:

linkly search "report" --endpoint http://192.168.1.100:60606/mcp --token your_lan_token
linkly status --endpoint http://192.168.1.100:60606/mcp --token your_lan_token

Remote Mode

Connect to your knowledge base from anywhere via the cloud tunnel. First, save your API key (from linkly.ai/dashboard):

linkly auth set-key lkai_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Then use --remote with any command:

linkly search "machine learning" --remote
linkly status --remote

--endpoint and --token are required together for LAN access. They cannot be combined with --remote. For remote access, use linkly auth set-key to save your API key.

Parameter Reference

Global Options

Option	Scope	Description
`--endpoint <URL>`	LAN	Connect to a specific MCP endpoint (e.g. `http://192.168.1.100:60606/mcp`), requires `--token`
`--token <token>`	LAN	Bearer token for LAN authentication (required with `--endpoint`, conflicts with `--remote`)
`--remote`	Remote	Connect via cloud tunnel at `https://mcp.linkly.ai` (conflicts with `--endpoint`)
`--json`	All commands	Output in JSON format (suitable for scripting and automation)
`-V, --version`	—	Display CLI version number
`-h, --help`	—	Display help information

--endpoint, --token, and --remote are available on search, grep, outline, read, and status commands. --endpoint alone (without --token) is also available on the mcp command. --json is available on all commands.

search Parameters

Parameter	Description	Default
`<QUERY>`	Search keywords or phrase (required)	—
`--limit <N>`	Maximum number of results	20
`--type <TYPES>`	Filter by document type (comma-separated)	All

outline Parameters

Parameter	Description	Default
`<ID...>`	Document ID (required, supports multiple)	—

grep Parameters

Parameter	Description	Default
`<PATTERN>`	Regular expression pattern (required)	—
`<DOC_ID>`	Document ID to search (required)	—
`-C, --context`	Lines of context before and after	3
`-B, --before`	Lines of context before each match	—
`-A, --after`	Lines of context after each match	—
`-i`	Case-insensitive matching	—
`--mode`	Output mode: `content` or `count`	content
`--limit`	Maximum matches (max 100)	20
`--offset`	Number of matches to skip	0
`--fuzzy-whitespace`	Fuzzy whitespace matching: `true` to force on, `false` to force off, omit for auto (PDF on, others off)	auto

read Parameters

Parameter	Description	Default
`<ID>`	Document ID (required)	—
`--offset <N>`	Starting line number (from 1)	1
`--limit <N>`	Number of lines to read (max 500)	200

Getting Started

Advanced Usage

Using Linkly AI CLI

Introduction to Linkly AI CLI

Terminal Search

MCP Bridge

Installation

Usage

Check Connection Status

Search Documents

View Document Outline

Search Patterns in Documents

Read Document Content

MCP Mode

Update CLI

Connection Modes

Local Mode (default)

LAN Mode

Remote Mode

Parameter Reference

Global Options

search Parameters

outline Parameters

grep Parameters

read Parameters

Getting Started

Advanced Usage

​Introduction to Linkly AI CLI

Terminal Search

MCP Bridge

​Installation

​Usage

​Check Connection Status

​Search Documents

​View Document Outline

​Search Patterns in Documents

​Read Document Content

​MCP Mode

​Update CLI

​Connection Modes

​Local Mode (default)

​LAN Mode

​Remote Mode

​Parameter Reference

​Global Options

​search Parameters

​outline Parameters

​grep Parameters

​read Parameters

Introduction to Linkly AI CLI

Installation

Usage

Check Connection Status

Search Documents

View Document Outline

Search Patterns in Documents

Read Document Content

MCP Mode

Update CLI

Connection Modes

Local Mode (default)

LAN Mode

Remote Mode

Parameter Reference

Global Options

search Parameters

outline Parameters

grep Parameters

read Parameters