Utiliser Linkly AI CLI

Présentation du Linkly AI CLI

Le Linkly AI CLI est un outil en ligne de commande qui se connecte au service MCP de Linkly AI Desktop, vous permettant de rechercher, parcourir et lire vos documents locaux depuis le terminal. Il sert également de passerelle entre les AI Agents (comme Claude Desktop, Cursor) et Linkly AI.

Recherche en terminal

Recherchez directement vos documents depuis la ligne de commande, idéal pour les développeurs et les utilisateurs avancés

Passerelle MCP

Fonctionne en mode MCP stdio, permettant à Claude Desktop, Cursor et d’autres outils IA d’appeler Linkly AI

Installation

macOS / Linux
Windows
Cargo

Exécutez dans le terminal :

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

Ou installez via Homebrew :

brew tap LinklyAI/tap
brew install linkly

Exécutez dans PowerShell :

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

Installez depuis crates.io (nécessite la chaîne d’outils Rust) :

cargo install linkly-ai-cli

Après l’installation, vérifiez :

linkly --version

Par défaut, le CLI découvre et se connecte à l’application Linkly AI Desktop locale via le fichier ~/.linkly/port. Vous pouvez également vous connecter à un appareil distant via le réseau local ou le tunnel cloud — voir Modes de connexion ci-dessous.

Méthodes d’utilisation

Le CLI suit le flux de travail progressif search → grep ou outline → read : d’abord rechercher pour trouver les documents cibles, puis utiliser grep pour localiser des motifs ou consulter le sommaire pour comprendre la structure, et enfin lire le contenu spécifique. Lorsque l’utilisateur évoque un conteneur (“dans mes notes Notion”, “dans mon dossier Dropbox”) dont le chemin réel est inconnu, appelez find-paths avant search pour le localiser.

Chaque sortie de commande réussie se termine par une ligne d’horodatage UTC [meta] now=2026-05-08T...Z (ou un champ _meta.now au niveau supérieur en mode JSON). Il s’agit de métadonnées que Desktop fournit aux assistants IA pour calculer des dates relatives comme « le mois dernier ». Les utilisateurs humains peuvent l’ignorer ; pour le scriptage, il est recommandé de filtrer la dernière ligne avant l’analyse ultérieure.

Vérifier l’état de la connexion

linkly status

Retourne l’état de fonctionnement de Linkly AI Desktop, le numéro de version, le nombre de documents indexés et l’état de l’indexation.

Rechercher des documents

linkly search "mots-clés ou expression"

Recherche dans vos documents locaux et retourne la liste des résultats les plus pertinents, incluant le titre, le chemin, la pertinence et un extrait du contenu. Paramètres courants :

# Limiter le nombre de résultats (par défaut 20, maximum 50)
linkly search "conception API" --limit 5

# Filtrer par type de document
linkly search "compte-rendu de réunion" --type pdf,docx

# Sortie au format JSON (adapté au traitement par script)
linkly search "rapport budgétaire" --json

# Limiter par fenêtre temporelle (rapports trimestriels Q3 2024)
linkly search "quarterly report" --modified-after 2024-07-01 --modified-before 2024-09-30

# Trier par date ("le plus récent", "le plus ancien" — sans plage fixe)
linkly search "weekly retro" --time-sort newest --limit 5

# Rechercher dans les fichiers audio et vidéo d'après ce qui y est dit
linkly search "we decided to postpone" --type audio,video

# Rechercher dans vos notes plutôt que dans vos fichiers
linkly search "onboarding checklist" --scope notes

--modified-after / --modified-before acceptent le format ISO 8601 UTC : une date simple 2024-01-01 (interprétée comme 00:00:00Z) ou un horodatage RFC 3339 complet 2024-01-01T00:00:00Z. --time-sort accepte newest / oldest ; omettez-le pour conserver l’ordre de pertinence hybride BM25 + vecteur.

--scope notes restreint les résultats à vos notes et ignore --library et --path-glob — ces filtres sont silencieusement écartés plutôt que rejetés.

Consulter le sommaire d’un document

linkly outline <DOC_ID>

Obtient le sommaire structuré et les métadonnées d’un document. Le DOC_ID est récupéré depuis les résultats de recherche. Vous pouvez consulter plusieurs documents à la fois, ou transmettre les ID via un pipe avec - :

linkly outline id1 id2 id3

# Obtenir le sommaire de tous les documents trouvés par une recherche, sans boucle shell
linkly search "architecture" --json | jq -r '.results[].doc_id' | linkly outline -

La fonctionnalité de sommaire est optimale pour les documents Markdown, DOCX, PowerPoint (PPTX) et EPUB, dont la structure de titres peut être analysée. Pour le texte brut ou les PDF sans signets, il est recommandé d’utiliser directement la commande read.

Rechercher des motifs dans les documents

linkly grep <PATTERN> <DOC_ID>...

Recherche les correspondances d’une expression régulière dans un ou plusieurs documents. À utiliser lorsque vous devez trouver un texte précis (termes, noms, dates, identifiants, etc.) :

# Trouver un motif dans un document
linkly grep "useState" 456

# Recherche insensible à la casse, avec lignes de contexte
linkly grep "error|warning" 1044 -C 3 -i

# Compter uniquement les correspondances
linkly grep "TODO" 591 --mode count

# Paginer les correspondances (ignorer les 20 premières, afficher les 20 suivantes)
linkly grep "import" 302 --offset 20 --limit 20

# Appliquer grep à tous les documents trouvés par une recherche
linkly search "deployment" --json | jq -r '.results[].doc_id' \
  | linkly grep "docker|kubernetes" -

Lire le contenu d’un document

linkly read <DOC_ID>...

Lit le contenu complet d’un ou plusieurs documents, avec des numéros de ligne. Pour les documents longs, vous pouvez lire par pages :

# À partir de la ligne 50, lire 100 lignes
linkly read <DOC_ID> --offset 50 --limit 100

# Inclure le texte OCR des images référencées dans la page
linkly read <DOC_ID> --image-text full

# Lire plusieurs documents à la fois, ou transmettre les ID via un pipe
linkly read id1 id2 id3
linkly search "onboarding" --json | jq -r '.results[].doc_id' | linkly read -

Avec --json, plusieurs documents sont affichés au format JSON Lines — un objet par ligne. Un seul ID produit toujours un objet unique : les scripts existants ne sont donc pas affectés.

Stratégie de pagination : Par défaut, chaque lecture récupère 200 lignes (maximum 500). Pour les documents longs, ajustez --offset pour lire progressivement :

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

Localisation de chemins (find-paths)

linkly find-paths --patterns <mot-clé,mot-clé,...>

Effectue une correspondance approximative des mots-clés sur le champ chemin de fichier des documents indexés, agrège les correspondances au niveau du dossier et retourne les meilleurs candidats. Cet outil est positionné comme un complément de search : lorsque l’utilisateur nomme un conteneur (“dans mes notes Notion”, “dans mon dossier Dropbox”) sans en connaître le chemin sur le disque, appelez d’abord find-paths, puis transmettez un segment distinctif du chemin retourné comme --path-glob à search. Lorsqu’un nom de dossier contient des métacaractères glob (* ? [), utilisez directement le champ path_glob retourné — il est déjà échappé pour correspondre littéralement à ce dossier. Flux de travail typique en deux étapes :

# Étape 1 : localiser le chemin réel
linkly find-paths --patterns Notion,notion --limit 5
# Supposons que cela retourne .../Documents/Notion-Export-abc/workspace (1240 fichiers)

# Étape 2 : rechercher dans ce conteneur
linkly search "shopping receipt" --path-glob "*Notion-Export*"

Correspondance par variantes : --patterns prend une liste de mots-clés séparés par des virgules, combinés en interne par OR contre le chemin. Passez plusieurs variantes en un seul appel (paires de traduction, casse, identifiants réels d’application) pour maximiser le rappel au premier coup :

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

find-paths est un outil de “recherche de dossiers”, pas de “recherche de fichiers” : seules les correspondances sur des segments de répertoire comptent. Si les mots-clés ne correspondent qu’au segment du nom de fichier (un “fichier orphelin”), ils sont silencieusement écartés. Si une requête ne renvoie aucun dossier alors que vous attendez des correspondances, repassez à un appel direct à linkly search sans --path-glob.

Notes

Linkly AI conserve de courtes notes Markdown dans le dossier de votre bibliothèque. Ce sont des fichiers locaux ordinaires — jamais téléversés — et ils sont indexés comme n’importe quel autre document.

# Les lister, de la plus récente à la plus ancienne
linkly list --scope notes

# Filtrer par tag
linkly list --scope notes --tags project,urgent

# En écrire une
linkly note-save --mode create --content "Remember to renew the certificate" --tags ops

# Transmettre un contenu long via un pipe plutôt que de le mettre entre guillemets
some-command | linkly note-save --mode create --content -

La modification d’une note existante nécessite son note_id et sa version actuelle, tous deux retournés par linkly list --scope notes :

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

Les #tag présents dans le corps de la note sont les tags de celle-ci — --tags ne fait qu’ajouter (pour retirer un tag, effacez son #tag du contenu). Sur les Desktop antérieurs à la 0.11.0, en revanche, --tags est obligatoire lors d’une modification et vaut remplacement intégral. --base-version est un contrôle de concurrence : si la note a changé depuis que vous l’avez lue, la commande échoue avec NOTE_VERSION_CONFLICT au lieu d’écraser le contenu. Le contenu d’une note se limite à un sous-ensemble restreint de Markdown (paragraphes, gras, barré, listes) ; les titres, le code, les liens et les tableaux sont rejetés.

Complétion du shell

linkly completions <SHELL>

Affiche un script de complétion pour bash, zsh, fish, powershell ou elvish.

zsh
bash
fish
PowerShell

mkdir -p ~/.zfunc
linkly completions zsh > ~/.zfunc/_linkly
# À ajouter à ~/.zshrc si ce n'est pas déjà fait :
#   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

Ouvrez ensuite un nouveau shell. Le script est statique — il ne contacte jamais Linkly AI Desktop : il fonctionne donc même lorsque l’application est fermée et ne peut pas ralentir votre invite de commande.

Mode MCP

linkly mcp

Fonctionne en mode serveur MCP stdio, exposant les outils de Linkly AI aux clients IA compatibles MCP. C’est l’amont qui détermine ce que le client peut atteindre :

Commande	Portée
`linkly mcp`	L’application de bureau locale — uniquement votre contenu local
`linkly mcp --endpoint <url>`	Une application de bureau du réseau local — même périmètre de contenu
`linkly mcp --remote`	La passerelle cloud — le contenu local et les bibliothèques cloud liées

--remote est le seul mode passerelle capable d’atteindre les bibliothèques cloud. Il nécessite d’avoir enregistré au préalable une API Key (voir Mode distant).

Configurer Claude Desktop et d’autres applications IA locales : Ajoutez le contenu suivant au fichier de configuration de Claude Desktop ou d’autres applications :

macOS / Linux
Windows

Éditez ~/.config/Claude/claude_desktop_config.json :

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

Éditez %APPDATA%\Claude\claude_desktop_config.json :

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

Configurer Cursor : Dans Cursor, ouvrez Settings → MCP Servers → Add Server, et ajoutez :

Name: linkly-ai
Command: linkly mcp

Mettre à jour le CLI

linkly self-update

Vérifie et met à jour automatiquement vers la dernière version. Le CLI vérifie également les mises à jour en arrière-plan à chaque démarrage ; si une nouvelle version est disponible, il vous invitera à exécuter cette commande.

Modes de connexion

Le CLI prend en charge trois façons de se connecter à votre base de connaissances Linkly AI :

Mode	Options	Fonctionnement
Local	(par défaut, aucune option)	Découvre automatiquement l’application de bureau via `~/.linkly/port`
Réseau local	`--endpoint <url> --token <token>`	Connexion directe à un autre appareil de votre réseau local
Distant	`--remote`	Connexion via le tunnel cloud `https://mcp.linkly.ai`, avec une API Key

Mode local (par défaut)

Aucune option supplémentaire n’est nécessaire. Le CLI lit ~/.linkly/port pour trouver l’application de bureau en cours d’exécution :

linkly search "machine learning"
linkly status

Mode réseau local

Connectez-vous à une instance de Linkly AI qui s’exécute sur un autre appareil de votre réseau local. Le jeton d’accès se trouve dans l’application de bureau, sous Paramètres → 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

Mode distant

Connectez-vous à votre base de connaissances depuis n’importe où via le tunnel cloud. Enregistrez d’abord votre API Key (obtenue sur linkly.ai/dashboard) :

linkly auth set-key lkai_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Utilisez ensuite --remote avec n’importe quelle commande :

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

Vous pouvez à tout moment vérifier ou supprimer la clé enregistrée :

linkly auth status   # quelle clé est utilisée, si elle est valide, et votre formule
linkly auth logout   # supprimer les identifiants enregistrés

--endpoint et --token doivent être fournis ensemble pour l’accès au réseau local. Ils ne peuvent pas être combinés avec --remote. Pour l’accès distant, utilisez linkly auth set-key afin d’enregistrer votre API Key.

Description des paramètres

Options globales

Option	Portée	Description
`--endpoint <URL>`	Réseau local	Spécifier le point de terminaison MCP (ex. `http://192.168.1.100:60606/mcp`), nécessite `--token`
`--token <token>`	Réseau local	Jeton Bearer pour l’authentification sur le réseau local (obligatoire avec `--endpoint`, incompatible avec `--remote`)
`--remote`	Distant	Connexion via le tunnel cloud `https://mcp.linkly.ai` (incompatible avec `--endpoint`)
`--json`	Toutes commandes	Sortie au format JSON (adapté aux scripts et à l’automatisation)
`--exit-code`	Toutes commandes	Distinguer « rien trouvé » (code 1) de « échec » (code 2) — voir Codes de sortie
`-V, --version`	—	Afficher la version du CLI
`-h, --help`	—	Afficher l’aide

--endpoint, --token et --remote sont disponibles sur les commandes documentaires (search, grep, outline, read, list, note-save, find-paths, explore, list-libraries) ainsi que sur status et doctor. La commande mcp accepte --endpoint ou --remote, mais pas --token. --json et --exit-code sont disponibles partout.

Codes de sortie

Par défaut, le CLI utilise les deux valeurs conventionnelles : 0 en cas de succès, 1 en cas d’échec. Notez qu’un « succès » inclut le fait de ne rien trouver — une recherche sans résultat sort tout de même avec le code 0. Passez --exit-code pour distinguer les deux cas :

Code	Signification
`0`	Exécutée et a produit au moins un résultat
`1`	Exécutée correctement, mais aucune correspondance
`2`	Échec (connexion, authentification, arguments invalides, erreurs)

# N'ouvre le rapport que si la recherche a réellement trouvé quelque chose
linkly search "quarterly report" --exit-code && open-report

Cette option est facultative car elle change la signification de 1. Sans elle, 1 signifie « échec » — ce que testent les scripts existants.

Paramètres de search

Paramètre	Description	Valeur par défaut
`<QUERY>`	Mots-clés ou expression de recherche (obligatoire)	—
`--limit <N>`	Nombre maximum de résultats retournés (1-50)	20
`--type <TYPES>`	Filtrer par type de document (séparés par des virgules) : `pdf`, `docx`, `pptx`, `epub`, `md`, `txt`, `html`, `image`, `audio`, `video`	Tous
`--library <NAME>`	Restreindre la recherche à une bibliothèque spécifique	—
`--path-glob <PATTERN>`	Filtrer par chemin de fichier ; recherché comme sous-chaîne (n’importe où, sans `*` en début ou fin). Lorsque le chemin réel est inconnu, exécutez d’abord `linkly find-paths`	—
`--modified-after <ISO>`	Borne inférieure incluse sur la date de modification. ISO 8601 UTC : date simple `2024-01-01` ou complète `2024-01-01T00:00:00Z`	—
`--modified-before <ISO>`	Borne supérieure incluse sur la date de modification. Même format que `--modified-after`	—
`--time-sort <MODE>`	Réordonnement temporel : `newest` / `oldest`. Omettez pour conserver l’ordre de pertinence	—
`--scope <SCOPE>`	`folder` recherche dans tout le contenu indexé ; `notes` restreint les résultats à vos notes et ignore `--library` / `--path-glob`	folder
`--tags <LIST>`	Tags de notes séparés par des virgules ; ne retourne que les documents les portant tous	—

Paramètres de find-paths

Paramètre	Description	Valeur par défaut
`--patterns <LIST>`	Liste de mots-clés séparés par des virgules (obligatoire). Plusieurs mots-clés sont combinés par OR ; passez plusieurs variantes (paires de traduction, casse). Insensible à la casse pour ASCII ; CJK littéral.	—
`--library <NAME>`	Restreindre à une bibliothèque spécifique	—
`--limit <N>`	Nombre maximum de dossiers candidats (1-50)	10

Paramètres de outline

Paramètre	Description	Valeur par défaut
`<ID>...`	ID des documents (obligatoire, plusieurs possibles). Passez `-` pour lire les ID depuis l’entrée standard, un par ligne	—

Paramètres de grep

Paramètre	Description	Valeur par défaut
`<PATTERN>`	Motif d’expression régulière (obligatoire)	—
`<DOC_ID>...`	ID des documents à parcourir (obligatoire, plusieurs possibles). Passez `-` pour lire les ID depuis l’entrée standard	—
`-C, --context`	Nombre de lignes de contexte avant et après	3
`-B, --before`	Nombre de lignes de contexte avant chaque correspondance	—
`-A, --after`	Nombre de lignes de contexte après chaque correspondance	—
`-i`	Correspondance insensible à la casse	—
`--mode`	Mode de sortie : `content` ou `count`	content
`--limit`	Nombre maximum de correspondances (maximum 100)	20
`--offset`	Nombre de correspondances à ignorer	0
`--fuzzy-whitespace`	Correspondance approximative des espaces : `true` pour forcer l’activation, `false` pour forcer la désactivation, omettre pour le mode automatique (activé pour les PDF, désactivé sinon)	auto

Paramètres de read

Paramètre	Description	Valeur par défaut
`<ID>...`	ID des documents (obligatoire, plusieurs possibles). Passez `-` pour lire les ID depuis l’entrée standard	—
`--offset <N>`	Numéro de ligne de départ (à partir de 1)	1
`--limit <N>`	Nombre de lignes à lire (maximum 500)	200
`--image-text <DETAIL>`	Niveau de détail des images référencées dans la page : `none` (correspondance seule), `abstract` (extrait), `full` (texte OCR intégré)	abstract

Paramètres de list

Paramètre	Description	Valeur par défaut
`--scope <SCOPE>`	Conteneur à lister : `folder` (fichiers indexés sous un répertoire), `library` (les fichiers d’une bibliothèque) ou `notes` (obligatoire)	—
`--library <LIB>`	Quelle bibliothèque, avec `--scope library` — un nom, `local://<id>` ou `cloud://<owner>/<slug>` (distant)	—
`--path <DIR>`	Répertoire à lister — chemin absolu en local, préfixe relatif pour les bibliothèques cloud	—
`--type <LIST>`	Types de document séparés par des virgules (`folder` / `library` uniquement), p. ex. `pdf,docx`	tous
`--modified-after <DATE>`	Seulement les éléments modifiés à cette date ou après (`folder` / `library` uniquement). ISO 8601, p. ex. `2026-01-01`	—
`--modified-before <DATE>`	Seulement les éléments modifiés à cette date ou avant. Même format	—
`--tags <LIST>`	Tags séparés par des virgules (`notes` uniquement) ; ne retourne que les éléments les portant tous	—
`--limit <N>`	Nombre maximum d’éléments (maximum 200 ; plafonné à 50 tant que les extraits sont activés)	50
`--offset <N>`	Décalage de pagination	0
`--sort <ORDER>`	`recent` (plus récent d’abord), `oldest` ou `name`	recent
`--snippet` / `--no-snippet`	Forcer les extraits activés / désactivés (mutuellement exclusifs). Par défaut : activés pour `notes`, désactivés pour `folder` / `library`	selon scope

Paramètres de note-save

Paramètre	Description	Valeur par défaut
`--mode <MODE>`	`create` crée une nouvelle note ; `edit` en réécrit une (nécessite `--note-id` et `--base-version`)	—
`--content <TEXT>`	Corps de la note (obligatoire). Passez `-` pour le lire depuis l’entrée standard	—
`--note-id <UUID>`	Note à modifier, obtenue via `linkly list --scope notes`	—
`--base-version <HASH>`	Version actuelle de la note, obtenue via `linkly list --scope notes`. Rejette l’écriture si la note a changé entre-temps	—
`--tags <LIST>`	Tags séparés par des virgules, à ajouter — pour retirer un tag, effacez son `#tag` du contenu	—
`--app-name <NAME>`	Nom d’affichage de l’application qui héberge la conversation ; affiché comme badge de source de la note. 64 caractères maximum	—

Paramètres de completions

Paramètre	Description	Valeur par défaut
`<SHELL>`	`bash`, `zsh`, `fish`, `powershell` ou `elvish` (obligatoire)	—

Démarrage rapide

Fonctionnalités principales

Connecter vos outils IA

Pour les Agents IA

Utiliser Linkly AI CLI

Présentation du Linkly AI CLI

Recherche en terminal

Passerelle MCP

Installation

Méthodes d’utilisation

Vérifier l’état de la connexion

Rechercher des documents

Consulter le sommaire d’un document

Rechercher des motifs dans les documents

Lire le contenu d’un document

Localisation de chemins (find-paths)

Notes

Complétion du shell

Mode MCP

Mettre à jour le CLI

Modes de connexion

Mode local (par défaut)

Mode réseau local

Mode distant

Description des paramètres

Options globales

Codes de sortie

Paramètres de search

Paramètres de find-paths

Paramètres de outline

Paramètres de grep

Paramètres de read

Paramètres de list

Paramètres de note-save

Paramètres de completions

​Présentation du Linkly AI CLI

Recherche en terminal

Passerelle MCP

​Installation

​Méthodes d’utilisation

​Vérifier l’état de la connexion

​Rechercher des documents

​Consulter le sommaire d’un document

​Rechercher des motifs dans les documents

​Lire le contenu d’un document

​Localisation de chemins (find-paths)

​Notes

​Complétion du shell

​Mode MCP

​Mettre à jour le CLI

​Modes de connexion

​Mode local (par défaut)

​Mode réseau local

​Mode distant

​Description des paramètres

​Options globales

​Codes de sortie

​Paramètres de search

​Paramètres de find-paths

​Paramètres de outline

​Paramètres de grep

​Paramètres de read

​Paramètres de list

​Paramètres de note-save

​Paramètres de completions

Présentation du Linkly AI CLI

Installation

Méthodes d’utilisation

Vérifier l’état de la connexion

Rechercher des documents

Consulter le sommaire d’un document

Rechercher des motifs dans les documents

Lire le contenu d’un document

Localisation de chemins (find-paths)

Notes

Complétion du shell

Mode MCP

Mettre à jour le CLI

Modes de connexion

Mode local (par défaut)

Mode réseau local

Mode distant

Description des paramètres

Options globales

Codes de sortie

Paramètres de search

Paramètres de find-paths

Paramètres de outline

Paramètres de grep

Paramètres de read

Paramètres de list

Paramètres de note-save

Paramètres de completions