Uso de Linkly AI CLI

Introducción a Linkly AI CLI

Linkly AI CLI es una herramienta de línea de comandos que, conectándose al servicio MCP de Linkly AI Desktop, le permite buscar, explorar y leer documentos locales desde la terminal. También funciona como puente entre AI Agent (como Claude Desktop, Cursor) y Linkly AI.

Búsqueda en terminal

Busque sus documentos directamente desde la línea de comandos, ideal para desarrolladores y usuarios avanzados

Puente MCP

Se ejecuta en modo MCP stdio, permitiendo que herramientas de IA como Claude Desktop y Cursor invoquen Linkly AI

Instalación

macOS / Linux
Windows
Cargo

Ejecute en la terminal:

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

O instale mediante Homebrew:

brew tap LinklyAI/tap
brew install linkly

Ejecute en PowerShell:

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

Instale desde crates.io (requiere la cadena de herramientas Rust):

cargo install linkly-ai-cli

Después de la instalación, verifique:

linkly --version

Antes de ejecutar CLI, debe iniciar la aplicación Linkly AI Desktop. CLI descubrirá y se conectará automáticamente al servicio MCP de la aplicación de escritorio a través del archivo ~/.linkly/port.

Métodos de uso

CLI sigue el flujo de trabajo progresivo search → outline → read: primero buscar para encontrar el documento objetivo, luego ver el esquema para entender la estructura, y finalmente leer el contenido específico. Cuando el usuario menciona un contenedor (“en mis notas de Notion”, “en mi carpeta de Dropbox”) cuya ruta real no se conoce, llame a find-paths antes de search para localizarla.

Cada salida de comando exitosa termina con una línea de marca de tiempo UTC [meta] now=2026-05-08T...Z (o un campo _meta.now de nivel superior en modo JSON). Estos son metadatos que Desktop proporciona a los asistentes de IA para calcular fechas relativas como “el mes pasado”. Los usuarios humanos pueden ignorarlos; al procesar con scripts, se recomienda filtrar la última línea antes del análisis posterior.

Verificar el estado de conexión

linkly status

Devuelve el estado de ejecución de Linkly AI Desktop, la versión, el número de documentos indexados y el estado de la indexación.

Buscar documentos

linkly search "palabras clave o frase"

Busca en sus documentos locales y devuelve la lista de resultados más relevantes, incluyendo título, ruta, relevancia y resumen del contenido. Parámetros frecuentes:

# Limitar el número de resultados (predeterminado 20, máximo 50)
linkly search "diseño de API" --limit 5

# Filtrar por tipo de documento
linkly search "acta de reunión" --type pdf,docx

# Salida en formato JSON (adecuado para procesamiento por scripts)
linkly search "informe de presupuesto" --json

# Limitar por ventana temporal (informes trimestrales del Q3 2024)
linkly search "quarterly report" --modified-after 2024-07-01 --modified-before 2024-09-30

# Ordenar por fecha ("el más reciente", "el más antiguo" — sin rango fijo)
linkly search "weekly retro" --time-sort newest --limit 5

# Buscar en audio y vídeo por lo que se dijo en ellos
linkly search "we decided to postpone" --type audio,video

# Buscar en sus notas en lugar de en sus archivos
linkly search "onboarding checklist" --scope notes

--modified-after / --modified-before aceptan formato ISO 8601 UTC: una fecha simple 2024-01-01 (interpretada como 00:00:00Z) o una marca de tiempo RFC 3339 completa 2024-01-01T00:00:00Z. --time-sort acepta newest / oldest; omítalo para preservar el orden de relevancia híbrido BM25 + vectorial.

--scope notes limita los resultados a sus notas e ignora --library y --path-glob: esos filtros se descartan silenciosamente en lugar de producir un error.

Ver el esquema del documento

linkly outline <DOC_ID>

Obtiene el esquema estructurado y los metadatos del documento. DOC_ID se obtiene de los resultados de búsqueda. Permite ver múltiples documentos a la vez, o pasar los ID mediante una tubería con -:

linkly outline id1 id2 id3

# Obtener el esquema de todo lo que encontró una búsqueda, sin bucles de shell
linkly search "architecture" --json | jq -r '.results[].doc_id' | linkly outline -

La función de esquema funciona mejor con documentos Markdown, DOCX, PowerPoint (PPTX) y EPUB, cuyos títulos pueden ser analizados estructuralmente. Para texto plano o PDF sin marcadores, se recomienda usar directamente el comando read.

Buscar patrones en documentos

linkly grep <PATTERN> <DOC_ID>...

Busca coincidencias de una expresión regular dentro de uno o varios documentos. Úselo cuando necesite encontrar texto específico (términos, nombres, fechas, identificadores, etc.):

# Buscar un patrón en un documento
linkly grep "useState" 456

# Sin distinguir mayúsculas y minúsculas, con líneas de contexto
linkly grep "error|warning" 1044 -C 3 -i

# Contar únicamente las coincidencias
linkly grep "TODO" 591 --mode count

# Paginar las coincidencias (omitir las primeras 20, mostrar las siguientes 20)
linkly grep "import" 302 --offset 20 --limit 20

# Aplicar grep a todo lo que encontró una búsqueda
linkly search "deployment" --json | jq -r '.results[].doc_id' \
  | linkly grep "docker|kubernetes" -

Leer el contenido del documento

linkly read <DOC_ID>...

Lee el contenido completo de uno o varios documentos con números de línea. Para documentos extensos, puede leer por páginas:

# Comenzar desde la línea 50, leer 100 líneas
linkly read <DOC_ID> --offset 50 --limit 100

# Incluir el texto OCR de las imágenes referenciadas en la página
linkly read <DOC_ID> --image-text full

# Leer varios documentos a la vez, o pasar los ID mediante una tubería
linkly read id1 id2 id3
linkly search "onboarding" --json | jq -r '.results[].doc_id' | linkly read -

Con --json, varios documentos se imprimen como JSON Lines: un objeto por línea. Un único ID sigue imprimiendo un solo objeto, por lo que los scripts existentes no se ven afectados.

Estrategia de paginación: Por defecto se leen 200 líneas por vez (máximo 500). Para documentos extensos, lea progresivamente ajustando --offset:

linkly read <DOC_ID> --offset 1 --limit 200    # Líneas 1-200
linkly read <DOC_ID> --offset 201 --limit 200  # Líneas 201-400
linkly read <DOC_ID> --offset 401 --limit 200  # Líneas 401-600

Localización de rutas (find-paths)

linkly find-paths --patterns <palabra,palabra,...>

Realiza una coincidencia aproximada de palabras clave contra el campo ruta de archivo de los documentos indexados, agrega las coincidencias a nivel de carpeta y devuelve los mejores candidatos. Está posicionada como una herramienta auxiliar de search: cuando el usuario nombra un contenedor (“en mis notas de Notion”, “en mi carpeta de Dropbox”) sin conocer su ruta en el disco, llame primero a find-paths, y luego pase un segmento distintivo de la ruta retornada como --path-glob a search. Cuando el nombre de una carpeta contiene metacaracteres glob (* ? [), use directamente el campo path_glob retornado — ya está escapado para coincidir literalmente con esa carpeta. Flujo de trabajo típico de dos pasos:

# Paso 1: localizar la ruta real
linkly find-paths --patterns Notion,notion --limit 5
# Supongamos que devuelve .../Documents/Notion-Export-abc/workspace (1240 archivos)

# Paso 2: buscar dentro de ese contenedor
linkly search "shopping receipt" --path-glob "*Notion-Export*"

Coincidencia con variantes: --patterns acepta una lista de palabras clave separadas por comas, combinadas internamente por OR contra la ruta. Pase varias variantes en una sola llamada (pares de traducción, mayúsculas/minúsculas, identificadores reales de aplicación) para maximizar la recuperación al primer intento:

linkly find-paths --patterns Notion,notion,Notion-Export
linkly find-paths --patterns Slack,slack --library work-notes

find-paths es una herramienta para “encontrar carpetas”, no para “encontrar archivos”: solo cuentan las coincidencias en segmentos de directorio. Si las palabras clave coinciden únicamente con el segmento de nombre de archivo (un “archivo huérfano”), se descartan silenciosamente. Si una consulta no devuelve carpetas a pesar de que espera coincidencias, recurra a llamar linkly search directamente sin --path-glob.

Notas

Linkly AI guarda notas breves en Markdown dentro de la carpeta de su biblioteca. Son archivos locales corrientes — nunca se suben — y se indexan como cualquier otro documento.

# Listarlas, de la más reciente a la más antigua
linkly list --scope notes

# Filtrar por etiqueta
linkly list --scope notes --tags project,urgent

# Escribir una
linkly note-save --mode create --content "Remember to renew the certificate" --tags ops

# Pasar un texto largo mediante una tubería en lugar de entrecomillarlo
some-command | linkly note-save --mode create --content -

Para editar una nota existente se necesitan su note_id y su version actual, que linkly list --scope notes devuelve:

linkly note-save --mode edit \
  --note-id <uuid> --base-version <version> \
  --tags ops --content "Updated text"

Los #tag que aparecen en el texto de la nota son sus etiquetas: --tags solo añade (para quitar una etiqueta hay que borrar su #tag del contenido). En los Desktop anteriores a la 0.11.0, en cambio, --tags es obligatorio al editar y se trata como el conjunto de reemplazo completo. --base-version es una comprobación de concurrencia: si la nota cambió desde que usted la leyó, el comando falla con NOTE_VERSION_CONFLICT en lugar de sobrescribirla. El contenido de las notas admite un subconjunto restringido de Markdown (párrafos, negrita, tachado, listas); los títulos, el código, los enlaces y las tablas se rechazan.

Autocompletado del shell

linkly completions <SHELL>

Imprime un script de autocompletado para bash, zsh, fish, powershell o elvish.

zsh
bash
fish
PowerShell

mkdir -p ~/.zfunc
linkly completions zsh > ~/.zfunc/_linkly
# Añada esto a ~/.zshrc si aún no está:
#   fpath=(~/.zfunc $fpath)
#   autoload -Uz compinit && compinit

linkly completions bash > /usr/local/etc/bash_completion.d/linkly

linkly completions fish > ~/.config/fish/completions/linkly.fish

linkly completions powershell | Out-String | Invoke-Expression

Abra después una nueva shell. El script es estático: nunca contacta con Linkly AI Desktop, por lo que funciona con la aplicación cerrada y no puede ralentizar su prompt.

Modo MCP

linkly mcp

Se ejecuta en modo servidor MCP stdio, exponiendo las herramientas de Linkly AI a clientes de IA compatibles con MCP. El destino al que se conecta el puente determina a qué puede acceder el cliente:

Comando	Alcance
`linkly mcp`	La aplicación de escritorio local: solo su contenido local
`linkly mcp --endpoint <url>`	Una aplicación de escritorio de la red local: el mismo límite de contenido
`linkly mcp --remote`	El servicio en la nube: contenido local y bibliotecas en la nube vinculadas

--remote es el único modo puente que puede alcanzar las bibliotecas en la nube. Requiere haber guardado antes una API Key (consulte Modo remoto).

Configurar aplicaciones de IA locales como Claude Desktop: Agregue el siguiente contenido al archivo de configuración de Claude Desktop u otras aplicaciones:

macOS / Linux
Windows

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

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

Edite %APPDATA%\Claude\claude_desktop_config.json:

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

Configurar Cursor: En Cursor, abra Settings → MCP Servers → Add Server y agregue:

Name: linkly-ai
Command: linkly mcp

Actualizar CLI

linkly self-update

Verifica y actualiza automáticamente a la última versión. CLI también comprueba actualizaciones en segundo plano con cada inicio y le notificará si hay una nueva versión disponible.

Modos de conexión

CLI admite tres formas de conectarse a su base de conocimiento de Linkly AI:

Modo	Opciones	Funcionamiento
Local	(predeterminado, sin opciones)	Descubre automáticamente la aplicación de escritorio a través de `~/.linkly/port`
Red local	`--endpoint <url> --token <token>`	Conexión directa con otro dispositivo de la red local
Remoto	`--remote`	Se conecta mediante el túnel en la nube `https://mcp.linkly.ai` usando una API Key

Modo local (predeterminado)

No requiere opciones adicionales. CLI lee ~/.linkly/port para encontrar la aplicación de escritorio en ejecución:

linkly search "machine learning"
linkly status

Modo de red local

Conéctese a una instancia de Linkly AI que se ejecuta en otro dispositivo de su red local. El token de acceso se encuentra en la aplicación de escritorio, en Ajustes → 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

Modo remoto

Conéctese a su base de conocimiento desde cualquier lugar mediante el túnel en la nube. Primero, guarde su API Key (obtenida en linkly.ai/dashboard):

linkly auth set-key lkai_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Después, use --remote con cualquier comando:

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

Consulte o borre la clave guardada en cualquier momento:

linkly auth status   # qué clave se está usando, si es válida y cuál es su plan
linkly auth logout   # elimina las credenciales guardadas

--endpoint y --token son obligatorios de forma conjunta para el acceso por red local. No pueden combinarse con --remote. Para el acceso remoto, use linkly auth set-key para guardar su API Key.

Descripción de parámetros

Opciones globales

Opción	Ámbito	Descripción
`--endpoint <URL>`	Red local	Conectarse a un endpoint MCP concreto (ej. `http://192.168.1.100:60606/mcp`); requiere `--token`
`--token <token>`	Red local	Token Bearer para la autenticación en red local (obligatorio con `--endpoint`, incompatible con `--remote`)
`--remote`	Remoto	Conectarse mediante el túnel en la nube `https://mcp.linkly.ai` (incompatible con `--endpoint`)
`--json`	Todos los comandos	Salida en formato JSON (adecuado para scripts y automatización)
`--exit-code`	Todos los comandos	Distinguir «no se encontró nada» (código 1) de «falló» (código 2) — consulte Exit Codes
`-V, --version`	—	Mostrar la versión de CLI
`-h, --help`	—	Mostrar información de ayuda

--endpoint, --token y --remote están disponibles en los comandos de documentos (search, grep, outline, read, list, note-save, find-paths, explore, list-libraries), además de status y doctor. El comando mcp acepta --endpoint o --remote, pero no --token. --json y --exit-code están disponibles en todos los comandos.

Exit Codes

De forma predeterminada, CLI usa los dos valores convencionales: 0 si tuvo éxito y 1 si falló. Tenga en cuenta que «éxito» incluye no encontrar nada: una búsqueda sin resultados sigue devolviendo 0. Pase --exit-code para distinguir ambos casos:

Código	Significado
`0`	Se ejecutó y produjo al menos un resultado
`1`	Se ejecutó correctamente pero no encontró ninguna coincidencia
`2`	Falló (conexión, autenticación, argumentos incorrectos, errores)

# Solo abre el informe cuando la búsqueda realmente encontró algo
linkly search "quarterly report" --exit-code && open-report

Esta opción no está activada por defecto porque cambia el significado de 1. Sin ella, 1 significa «falló», que es lo que comprueban los scripts existentes.

Parámetros de search

Parámetro	Descripción	Predeterminado
`<QUERY>`	Palabras clave o frase (obligatorio)	—
`--limit <N>`	Número máximo de resultados (1-50)	20
`--type <TYPES>`	Filtrar por tipo de documento (separado por comas): `pdf`, `docx`, `pptx`, `epub`, `md`, `txt`, `html`, `image`, `audio`, `video`	Todos
`--library <NAME>`	Restringir la búsqueda a una biblioteca específica	—
`--path-glob <PATTERN>`	Filtrar por ruta de archivo; búsqueda por subcadena (en cualquier posición, sin `*` al inicio o al final). Cuando la ruta real es desconocida, ejecute primero `linkly find-paths`	—
`--modified-after <ISO>`	Límite inferior inclusivo de la fecha de modificación. ISO 8601 UTC: fecha simple `2024-01-01` o completa `2024-01-01T00:00:00Z`	—
`--modified-before <ISO>`	Límite superior inclusivo de la fecha de modificación. Mismo formato que `--modified-after`	—
`--time-sort <MODE>`	Reordenamiento temporal: `newest` / `oldest`. Omitir para mantener el orden de relevancia	—
`--scope <SCOPE>`	`folder` busca en todo el contenido indexado; `notes` limita los resultados a sus notas e ignora `--library` / `--path-glob`	folder
`--tags <LIST>`	Etiquetas de notas separadas por comas; devuelve solo los documentos que las llevan todas	—

Parámetros de find-paths

Parámetro	Descripción	Predeterminado
`--patterns <LIST>`	Lista de palabras clave separadas por comas (obligatorio). Múltiples palabras se combinan por OR; pase varias variantes (pares de traducción, mayúsculas/minúsculas). Insensible a mayúsculas para ASCII; CJK literal.	—
`--library <NAME>`	Restringir a una biblioteca específica	—
`--limit <N>`	Número máximo de carpetas candidatas (1-50)	10

Parámetros de outline

Parámetro	Descripción	Predeterminado
`<ID>...`	ID de los documentos (obligatorio, admite múltiples). Pase `-` para leer los ID desde la entrada estándar, uno por línea	—

Parámetros de grep

Parámetro	Descripción	Predeterminado
`<PATTERN>`	Patrón de expresión regular (obligatorio)	—
`<DOC_ID>...`	ID de los documentos donde buscar (obligatorio, admite múltiples). Pase `-` para leer los ID desde la entrada estándar	—
`-C, --context`	Líneas de contexto antes y después	3
`-B, --before`	Líneas de contexto antes de cada coincidencia	—
`-A, --after`	Líneas de contexto después de cada coincidencia	—
`-i`	Coincidencia sin distinguir mayúsculas y minúsculas	—
`--mode`	Modo de salida: `content` o `count`	content
`--limit`	Número máximo de coincidencias (máximo 100)	20
`--offset`	Número de coincidencias a omitir	0
`--fuzzy-whitespace`	Coincidencia flexible de espacios en blanco: `true` para forzarla, `false` para desactivarla, omitir para modo automático (activa en PDF, inactiva en el resto)	auto

Parámetros de read

Parámetro	Descripción	Predeterminado
`<ID>...`	ID de los documentos (obligatorio, admite múltiples). Pase `-` para leer los ID desde la entrada estándar	—
`--offset <N>`	Línea de inicio (desde 1)	1
`--limit <N>`	Número de líneas a leer (máximo 500)	200
`--image-text <DETAIL>`	Nivel de detalle de las imágenes referenciadas en la página: `none` (solo la correspondencia), `abstract` (extracto), `full` (texto OCR insertado)	abstract

Parámetros de list

Parámetro	Descripción	Predeterminado
`--scope <SCOPE>`	Contenedor a listar: `folder` (archivos indexados bajo un directorio), `library` (los archivos de una biblioteca) o `notes` (obligatorio)	—
`--library <LIB>`	Qué biblioteca, con `--scope library` — un nombre, `local://<id>` o `cloud://<owner>/<slug>` (remoto)	—
`--path <DIR>`	Directorio a listar — ruta absoluta en local, prefijo relativo para bibliotecas en la nube	—
`--type <LIST>`	Tipos de documento separados por comas (solo `folder` / `library`), p. ej. `pdf,docx`	todos
`--modified-after <DATE>`	Solo elementos modificados en esa fecha o después (solo `folder` / `library`). ISO 8601, p. ej. `2026-01-01`	—
`--modified-before <DATE>`	Solo elementos modificados en esa fecha o antes. Mismo formato	—
`--tags <LIST>`	Etiquetas separadas por comas (solo `notes`); devuelve solo los elementos que las llevan todas	—
`--limit <N>`	Número máximo de elementos (máximo 200; limitado a 50 mientras los extractos están activados)	50
`--offset <N>`	Desplazamiento de paginación	0
`--sort <ORDER>`	`recent` (más recientes primero), `oldest` o `name`	recent
`--snippet` / `--no-snippet`	Forzar los extractos de cada elemento activados / desactivados (excluyentes). Por defecto: activados en `notes`, desactivados en `folder` / `library`	según scope

Parámetros de note-save

Parámetro	Descripción	Predeterminado
`--mode <MODE>`	`create` escribe una nota nueva; `edit` reescribe una existente (requiere `--note-id` y `--base-version`)	—
`--content <TEXT>`	Cuerpo de la nota (obligatorio). Pase `-` para leerlo desde la entrada estándar	—
`--note-id <UUID>`	Nota que se va a editar, obtenida de `linkly list --scope notes`	—
`--base-version <HASH>`	Versión actual de la nota, obtenida de `linkly list --scope notes`. Rechaza la escritura si la nota cambió mientras tanto	—
`--tags <LIST>`	Etiquetas separadas por comas que se quieren añadir: para quitar una hay que borrar su `#tag` del contenido	—
`--app-name <NAME>`	Nombre visible de la aplicación que aloja la conversación; se muestra como insignia de origen de la nota. Máximo 64 caracteres	—

Parámetros de completions

Parámetro	Descripción	Predeterminado
`<SHELL>`	`bash`, `zsh`, `fish`, `powershell` o `elvish` (obligatorio)	—

Inicio rápido

Funciones principales

Conecta tus herramientas de IA

Para Agentes de IA

Uso de Linkly AI CLI

Introducción a Linkly AI CLI

Búsqueda en terminal

Puente MCP

Instalación

Métodos de uso

Verificar el estado de conexión

Buscar documentos

Ver el esquema del documento

Buscar patrones en documentos

Leer el contenido del documento

Localización de rutas (find-paths)

Notas

Autocompletado del shell

Modo MCP

Actualizar CLI

Modos de conexión

Modo local (predeterminado)

Modo de red local

Modo remoto

Descripción de parámetros

Opciones globales

Exit Codes

Parámetros de search

Parámetros de find-paths

Parámetros de outline

Parámetros de grep

Parámetros de read

Parámetros de list

Parámetros de note-save

Parámetros de completions

​Introducción a Linkly AI CLI

Búsqueda en terminal

Puente MCP

​Instalación

​Métodos de uso

​Verificar el estado de conexión

​Buscar documentos

​Ver el esquema del documento

​Buscar patrones en documentos

​Leer el contenido del documento

​Localización de rutas (find-paths)

​Notas

​Autocompletado del shell

​Modo MCP

​Actualizar CLI

​Modos de conexión

​Modo local (predeterminado)

​Modo de red local

​Modo remoto

​Descripción de parámetros

​Opciones globales

​Exit Codes

​Parámetros de search

​Parámetros de find-paths

​Parámetros de outline

​Parámetros de grep

​Parámetros de read

​Parámetros de list

​Parámetros de note-save

​Parámetros de completions

Introducción a Linkly AI CLI

Instalación

Métodos de uso

Verificar el estado de conexión

Buscar documentos

Ver el esquema del documento

Buscar patrones en documentos

Leer el contenido del documento

Localización de rutas (find-paths)

Notas

Autocompletado del shell

Modo MCP

Actualizar CLI

Modos de conexión

Modo local (predeterminado)

Modo de red local

Modo remoto

Descripción de parámetros

Opciones globales

Exit Codes

Parámetros de search

Parámetros de find-paths

Parámetros de outline

Parámetros de grep

Parámetros de read

Parámetros de list

Parámetros de note-save

Parámetros de completions