Skip to main content

​
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

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
After installation, verify the installation: 
linkly --version
The CLI requires Linkly AI Desktop to be running. The CLI automatically discovers and connects to the desktop app’s MCP service via the ~/.linkly/port file.

​
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:
Edit ~/.config/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.

​
Parameter Reference

​
Global Options

OptionDescription
--endpoint <URL>Specify the MCP endpoint (auto-discovered from ~/.linkly/port by default)
--jsonOutput in JSON format (suitable for scripting and automation)
-V, --versionDisplay CLI version number
-h, --helpDisplay help information

​
search Parameters

ParameterDescriptionDefault
<QUERY>Search keywords or phrase (required)—
--limit <N>Maximum number of results20
--type <TYPES>Filter by document type (comma-separated)All

​
outline Parameters

ParameterDescriptionDefault
<ID...>Document ID (required, supports multiple)—

​
grep Parameters

ParameterDescriptionDefault
<PATTERN>Regular expression pattern (required)—
<DOC_ID>Document ID to search (required)—
-C, --contextLines of context before and after3
-B, --beforeLines of context before each match—
-A, --afterLines of context after each match—
-iCase-insensitive matching—
--modeOutput mode: content or countcontent
--limitMaximum matches (max 100)20
--offsetNumber of matches to skip0
--fuzzy-whitespaceFuzzy whitespace matching: true to force on, false to force off, omit for auto (PDF on, others off)auto

​
read Parameters

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