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:Or install via Homebrew:
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, callfind-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
Search Documents
--scope notes restricts results to your notes and ignores --library and --path-glob — those filters are silently dropped rather than rejected.View Document Outline
DOC_ID is obtained from search results. You can view multiple documents at once, or pipe the IDs in with -:
--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:
Search Patterns in Documents
Read Document Content
--offset to read progressively:
Find Paths (find-paths)
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:
--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:
Libraries and Overview (list-libraries, explore)
--library option of other commands.
--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.note_id and current version, both of which linkly list --scope notes returns:
Diagnose Connections (doctor)
--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
bash, zsh, fish, powershell or elvish.
- zsh
- bash
- fish
- PowerShell
MCP 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:
- macOS
- Windows
Edit
~/Library/Application Support/Claude/claude_desktop_config.json:- Name:
linkly-ai - Command:
linkly mcp --client cursor
Update CLI
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.
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:--lan with any command:
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: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:
--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:
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.
Parameter Reference
Global Options
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.
