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:
Or install via Homebrew:
If you already have Linkly AI Desktop, you can also install the CLI from the desktop app: click Install on the Connect an agent screen of the first-run wizard, which installs both the CLI and Skills; or click Install in the Linkly AI CLI row in the Advanced section of the Agent usage page in the main window. If One last step pops up, click Set up so your terminal can run the linkly command directly.
After installation, verify the installation:
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. When the user describes a container (“in my Notion notes”, “in my Dropbox papers folder”) whose actual path is unknown, call find-paths before search to discover the path.
Every successful command output ends with a [meta] now=2026-05-08T...Z UTC timestamp line (or a top-level _meta.now field in JSON mode). This is metadata Desktop provides to AI assistants for computing relative dates like “last month” — human users can ignore it; for scripting, you may want to filter out the last line before further parsing.

Check Connection Status

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

Search Documents

Searches your local documents and returns the most relevant results, including title, path, relevance score, and content snippet. Common parameters:
--modified-after / --modified-before accept ISO 8601 UTC: a bare date 2024-01-01 (treated as 00:00:00Z) or a full RFC 3339 timestamp 2024-01-01T00:00:00Z. --time-sort accepts newest / oldest; omit it to keep the default BM25 + vector relevance order.
--scope notes restricts results to your notes and ignores --library and --path-glob — those filters are silently dropped rather than rejected.

View Document Outline

Retrieves the structured outline and metadata of a document. DOC_ID is obtained from search results. You can view multiple documents at once, or pipe the IDs in with -:
When an outline is long, some nodes are collapsed. Use --expand to name the node IDs to expand, comma-separated; all other nodes stay collapsed. Without it, the CLI decides automatically which nodes to expand:
The outline feature works best with Markdown, DOCX, DOC, PowerPoint (PPTX), XLSX, CSV, EPUB, and RTF 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

Search for regex pattern matches inside one or more documents. Use when you need to find specific text (terms, names, dates, identifiers, etc.):

Read Document Content

Reads the full content of one or more documents, outputting text with line numbers. For long documents, you can read in pages:
With --json, several documents print as JSON Lines — one object per line. A single ID still prints a single object, so existing scripts are unaffected.
Pagination strategy: By default, 200 lines are read per request (max 500 lines). For long documents, adjust --offset to read progressively:

Find Paths (find-paths)

Fuzzy-matches keywords against the file path field of indexed documents, aggregates matches at folder granularity, and returns the top folder candidates. It is positioned as a helper for search: when the user names a container (“in my Notion notes”, “in my Dropbox papers folder”) but you don’t know its on-disk path, call find-paths first, then pass a distinctive segment of the returned path to search as --path-glob. When a folder name contains glob metacharacters (* ? [), use the returned path_glob field directly — it is already escaped to match that folder literally. Two-step workflow:
Variant matching: --patterns takes a comma-separated list of keywords, OR-matched against the path. Pass several variants in one call (translation pairs, casing, real app/SDK identifiers when known) to maximise first-pass recall:
find-paths is a “find folders” tool, not a “find files” tool: only matches on directory segments count. If keywords match only the filename segment (an “orphan file”), they are silently dropped. If a query returns zero folders even though you expect matching files, fall back to calling linkly search directly without --path-glob.

Libraries and Overview (list-libraries, explore)

Lists the available libraries. The library names it returns can be used in the --library option of other commands.
Gives an overview of all your documents or of a single library — useful for getting a sense of what’s there before you search. --library accepts a library name or local://<id>; with --remote you can also pass cloud://<owner>/<slug>.

Notes

Linkly AI keeps short Markdown notes in your library folder. They are ordinary local files — never uploaded — and they are indexed like any other document.
Editing an existing note needs its note_id and current version, both of which linkly list --scope notes returns:
Inline #tags in the note body are the note’s tags — --tags only adds (remove a tag by deleting its #tag marker from the content). Desktops older than 0.11.0 instead require --tags on edit and treat it as the full replacement set. --base-version is a concurrency check: if the note changed since you read it, the command fails with NOTE_VERSION_CONFLICT instead of overwriting. Note content is a restricted Markdown subset (paragraphs, bold, strikethrough, lists); headings, code, links and tables are rejected.

Diagnose Connections (doctor)

Checks the connection to the desktop app on this machine, and also any saved remote key or LAN connection. Each connection gets its own group of results, with advice on how to fix any failure. It exits 0 as long as at least one connection works. With --remote, --lan, or --endpoint / --token, it checks only that one connection, and the exit code reflects only that connection:

Manage Skills (skills)

install puts the Skills in ~/.agents/skills/linkly-ai and creates a link to it at ~/.claude/skills/linkly-ai. See Using Skills for details. When a new version of the Skills is available, the command output ends with a one-line notice, at most once every 4 hours. Set the environment variable LINKLY_NO_SKILLS_HINT=1 to turn it off. Set the variable in your MCP client’s configuration and the linkly mcp bridge stops showing it too.

Shell Completions

Prints a completion script for bash, zsh, fish, powershell or elvish.
Open a new shell afterwards. The script is static — it never contacts Linkly AI Desktop, so it works with the app closed and can’t slow down your prompt.

MCP Mode

Runs as a stdio MCP server, exposing Linkly AI’s tools to MCP-compatible AI clients. The upstream decides what the client can reach:
--remote is the only bridge mode that can reach cloud libraries. Sign in first with linkly auth login (see Remote Mode).
The bridge cannot connect to a desktop app on another device in your LAN. AI clients on the LAN should connect to the desktop app directly over HTTP (see LAN Access); clients that only support stdio can use linkly mcp --remote instead.
--client <name> names the application in the desktop app’s access log, as in the examples below. With --remote, the name is also sent to the cloud gateway. Configure Claude Desktop and other local AI apps: Add the following to the configuration file of Claude Desktop or similar apps:
Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
Configure Cursor: In Cursor, open Settings → MCP Servers → Add Server, and add:
  • Name: linkly-ai
  • Command: linkly mcp --client cursor

Update CLI

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: Without --lan or --remote, the CLI only connects to the desktop app on this machine.
An API key (starting with lkai_) and a LAN access token work like keys to your local library. Don’t paste them into any AI conversation (ChatGPT, Claude, Cursor, Codex, Doubao, Kimi, and so on), and don’t let an AI assistant run linkly auth set-key for you: conversations are sent to the model provider, kept in the chat history, and in some apps synced to the cloud. To let an AI assistant connect remotely, use the two-step linkly auth login below — you only approve in the browser. Run set-key yourself, in your own terminal. If a key has already appeared in a conversation, revoke it and create a new one in the dashboard; regenerate a LAN token under View MCP connection settings.

Local Mode (default)

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

LAN Mode

Connect to a Linkly AI instance running on another device in your local network. Get the address and token from that device: in its desktop app, open the Agent usage page, turn on Allow LAN access under Management, then click View MCP connection settings in the Integration section and copy them from the LAN section (see LAN Access for details). Then save them once on this machine, yourself, in your own terminal:
Then use --lan with any command:
If you’d rather not save them, you can pass the address and token directly each time:
If the token is regenerated, run auth set-key --lan again with the new token. When you no longer need it, remove the saved LAN config with linkly auth logout --lan.
Saving a LAN connection and the --lan flag require CLI 1.0.0 or later. The CLI can save only one LAN connection; running auth set-key --lan again overwrites the previously saved address and token. To connect to another device temporarily, use --endpoint and --token.

Remote Mode

Connect to your knowledge base from anywhere via the cloud tunnel. First, sign in once:
The CLI prints a one-time link and a confirmation code (XXXX-XXXX), and opens your browser when it can. Open the link on any device — your phone works fine if the CLI runs on a server — sign in, check that the code matches the one in your terminal, and click Authorize. The CLI then saves a newly issued API key. The link is valid for 10 minutes; the page shows the account you are authorizing, the confirmation code, the device asking for access (as reported by that device), and the permissions it gets. If you don’t want the CLI to try opening a browser, add --no-browser and it only prints the link. Then use --remote with any command:
Agents and scripts that can’t wait in the foreground split the login in two steps. The agent only hands you the link and the code; the CLI stores the key itself, so it never passes through the conversation. Run both in the same environment, as the same system user, with the same config directory:
--wait gives up after 300 seconds (change it with --timeout) with the code timeout; run it again while the link is still valid. In --json mode failures carry a code: timeout, expired, denied, no_pending_login, login_in_progress (use --wait, or --restart to start over), already_logged_in (run linkly auth logout first) and network. Every message names the command to run next. Each login creates a new API key named cli-<hostname>-xxxx, which you can see and revoke in the dashboard. An account can hold up to 10 API keys; when you’re at the limit, the authorization page says so. Signing in only proves which account you are — it doesn’t mean your cloud libraries or your desktop app are reachable. Prefer to paste a key? Create one in the dashboard and save it yourself, in your own terminal:
Check or clear the stored key at any time:
logout also revokes a key that auth login issued — it stops working within about 90 seconds. A key saved with set-key is only removed from this machine, since it may be in use elsewhere; revoke it in the dashboard if needed. Credentials, and a login still waiting for approval, live in ~/.linkly by default. Set LINKLY_CONFIG_DIR to keep them somewhere else — for example one directory per user when an agent serves several people from the same system account. Each directory holds one account. Discovery of the local desktop app (~/.linkly/port) is not affected.
--lan, --remote and --endpoint cannot be combined. --endpoint and --token are required together, and the saved LAN config is ignored in that case.

Parameter Reference

Global Options

--lan, --endpoint, --token and --remote are available on the document commands (search, grep, outline, read, list, note-save, find-paths, explore, list-libraries) plus status and doctor. The mcp command only accepts --remote. --json has no effect on auth set-key, self-update, skills install, skills update, completions, or mcp.

Exit Codes

By default the CLI uses the conventional two values: 0 on success, 1 on failure. Note that “success” includes finding nothing — a search with no hits still exits 0. Argument errors (a missing required argument, an invalid value, and so on) always exit 2, with or without --exit-code. Pass --exit-code to tell the two apart:
The flag is opt-in because it changes what 1 means. Without it, 1 is “failed” — which is what existing scripts test for.

search Parameters

find-paths Parameters

outline Parameters

grep Parameters

read Parameters

list Parameters

note-save Parameters

completions Parameters