# Utilisation

> HTML: https://remote.ivjn.us/docs/fr/usage/

Ce parcours s'adresse aux opérateurs : obtenir les outils en ligne de commande et côté appareil, se connecter, ajouter un appareil, le connecter, puis exécuter une commande distante et ouvrir un shell. La console navigateur, la console mobile, l'Agent Android, l'appairage et la mise à jour automatique sont décrits dans les liens en fin de page ; leurs étapes ne sont pas répétées ici.

Remplacez les adresses et jetons des exemples par les vôtres. Un jeton n'est affiché qu'à sa création : ne l'enregistrez pas dans le dépôt.

**Identités nommées et autorisations de compte.** L’option globale `--profile <name>` prime sur `REMOTE_CLI_PROFILE`. `config.toml`, les clés privées, la confiance racine et les caches d’autorisations sont conservés dans `<config_base>/remote-cli/profiles/<name>/`. `config_base` conserve les conventions XDG_CONFIG_HOME, HOME/.config ou Windows APPDATA. Les noms acceptent 1 à 64 lettres ASCII, chiffres, points, tirets ou soulignements, sauf `.` et `..`. Un profil nommé prime sur `REMOTE_CLI_CONFIG` ; sans profil, les chemins et `REMOTE_CLI_CONFIG` restent inchangés. Connectez chaque profil séparément et sélectionnez-le lors des appels suivants.

`operator set` accepte un ID de compte ou un nom unique ; les arguments d’appareil sont des ID. `--restricted` limite la visibilité aux appareils explicitement autorisés ; `--unrestricted` rétablit la visibilité selon le rôle. Seul le superadmin peut modifier la portée. Il gère les rôles et autorisations ; en son absence, les admins agissent dans leur portée autorisée, sans modifier leurs propres droits. `operator grant list` ne renvoie que les autorisations visibles. Les droits en base et les autorisations signées sont deux contrôles distincts : leur modification ne remplace pas `seal approve`. La création ne permet pas d’attribuer atomiquement la portée. Conservez le jeton unique de `operator add`, puis utilisez `operator set` / `operator grant set` comme requêtes séparées.

Toutes les actions operator acceptent `-o text|json|xml`. JSON utilise `op=list|add|set|grant_list|grant_set|grant_remove`. `set` reçoit `operator` et au moins un champ parmi `role` / `restricted` ; `grant_set` reçoit `operator`, `device` et le booléen obligatoire `can_manage`. `grant_list` accepte `operator` en option ; `grant_remove` reçoit `operator` et `device`. Ne combinez pas `--json` avec une sous-commande.

```bash
remote-cli --profile alice login --server https://exchange.example.com
remote-cli --profile root operator set alice --restricted
remote-cli --profile root operator set alice --role readonly
remote-cli --profile root operator grant list --operator alice -o json
remote-cli --profile root operator grant set alice lab --view
remote-cli --profile root operator grant set alice lab --manage
remote-cli --profile root operator grant remove alice lab
remote-cli --profile root operator set alice --unrestricted
remote-cli --profile root operator --json '{"op":"grant_set","operator":"alice","device":"lab","can_manage":false}' -o json
```


## Requêtes et sorties XML

Vérifiez les options de la version installée avec `remote-cli --help`. `--xml` et `--xml-file` ajoutent une entrée XML aux requêtes `--json` / `--json-file` existantes. Les quatre entrées sont exclusives et fournissent le corps complet : ne les combinez pas avec les mêmes options ou sous-commandes. Les arguments positionnels des appareils restent identiques. Entrée et sortie sont indépendantes ; `-o text|json|xml` utilise le texte par défaut.

```powershell
remote-cli device --xml '<request><op>list</op></request>' -o xml
remote-cli exec my-device --xml-file request.xml -o xml
```

Une feuille est une chaîne par défaut ; un élément avec des enfants est un objet. Utilisez `type="number"`, `type="boolean"`, `type="array"` et `type="null"` pour les nombres, booléens, tableaux et null. Les tableaux contiennent des `<item>` ; les objets vides exigent `type="object"`. Utilisez `<field name="arbitrary key">value</field>` pour une clé quelconque et `<request type="object"/>` pour une requête vide.

```xml
<request>
  <command>echo hello</command>
  <timeout_secs type="number">30</timeout_secs>
  <hold type="boolean">false</hold>
  <env><GREETING>hello &amp; welcome</GREETING></env>
</request>
```

La racine de sortie est `<response type="...">`, les membres des objets sont `<field name="..." type="...">` et ceux des tableaux `<item type="...">`. Les types sont explicites et le texte est échappé selon XML 1.0. Les erreurs à l’exécution renvoient `ok=false` / `error` avec un code de sortie non nul ; les erreurs de syntaxe restent sur `stderr`.

La sortie XML prend en charge `device list/update`, `operator list/add/set/grant`, `exec`, `session list/kill`, `ui`, `ubus`, `sensors`, `net`, `metrics`, `preset`, `audit`, `browser`, y compris les opérations sur les tâches exec. Les autres commandes refusent explicitement `-o xml` ; elles acceptent toujours les requêtes XML avec leurs formats de sortie habituels.

Les flux `exec` / `sensors --live` / `browser session` produisent un document XML complet par ligne, à analyser séparément. Les événements de données exec contiennent `stream` / `encoding=base64` / `data` ; Base64 conserve les octets originaux. Un exec normal se termine par son état de sortie. L’entrée interactive de `browser session` reste en JSON Lines. `ui xml` sans `-o xml` conserve le XML brut de la hiérarchie UI.

Les requêtes sont limitées à 1 MiB et 64 niveaux. Les champs dupliqués, le mélange de texte et d’éléments, les DTD et les entités externes sont refusés. Choisissez JSON pour conserver des caractères de contrôle non représentables en XML 1.0. La configuration Agent et le protocole réseau restent en JSON ; XML ne convertit que les entrées et sorties du CLI.

## Obtenir remote-cli et remote-agent

Compilez depuis la racine du dépôt :

```bash
cargo build --release
```

L'outil en ligne de commande est `target/release/remote-cli`. Cette commande compile aussi `target/release/remote-agent`. Pour les appareils dont la mémoire flash est limitée, privilégiez l'agent optimisé en taille :

```bash
cargo build -p agent --no-default-features --profile release-small
```

Le résultat est `target/release-small/remote-agent`.

Sous Windows, Linux et macOS, les scripts d'installation du site permettent aussi d'installer l'un de ces exécutables en une commande ; voir [Déploiement multiplateforme](/docs/fr/platform-installation.md#installation-en-une-commande-windows--linux--macos--freebsd--netbsd). Les commandes suivantes supposent que `remote-cli` et `remote-agent` sont dans le `PATH` ; après une compilation locale, utilisez plutôt les chemins `target/...` ci-dessus.

Pour un relais auto-hébergé, suivez d'abord le [guide de développement](/docs/fr/development.md) afin de lancer `exchange` avec `DATABASE_URL`, puis récupérez le jeton administrateur dans les journaux de démarrage. Pour une instance publique, demandez un jeton opérateur à l'administrateur.

## Connexion

```bash
remote-cli login --server http://127.0.0.1:8080 --token '<运维令牌>'
```

`--server` accepte `http://` ou `https://`. Le CLI en déduit une adresse WebSocket de même niveau de sécurité : `https` devient `wss`, et `http` devient `ws`.

Après connexion, la configuration est enregistrée dans :

- Linux / macOS : `$XDG_CONFIG_HOME/remote-cli/config.toml`, ou `~/.config/remote-cli/config.toml` si `XDG_CONFIG_HOME` n'est pas défini.
- Windows : `%APPDATA%\remote-cli\config.toml`.

Le fichier contient uniquement `server` et `token`. Définissez `REMOTE_CLI_CONFIG` pour utiliser un autre chemin. Les commandes `device`, `exec` et `shell` lisent ensuite cette configuration ; inutile de fournir le jeton à chaque fois.

## Ajouter un appareil

```bash
remote-cli device add lab-router --name "实验室路由"
```

`<id>` est l'identifiant de l'appareil. Il accepte uniquement lettres, chiffres et `-` `_` `.`, avec une longueur maximale de 64 caractères. `--name` est facultatif ; sans lui, le nom affiché correspond à l'identifiant. Le jeton d'appareil renvoyé par la commande n'est affiché qu'une fois.

## Lancer l'agent

Sur la machine à gérer, lancez l'Agent avec le serveur, l'identifiant d'appareil et le jeton obtenu :

```bash
remote-agent --server wss://127.0.0.1:8080 --device-id lab-router --token '<设备令牌>'
```

Ces trois paramètres peuvent aussi être fournis par `REMOTE_SERVER`, `REMOTE_DEVICE_ID` et `REMOTE_TOKEN`.

`--server` doit commencer par `ws://` ou `wss://`. Si seul l'hôte est fourni (par exemple `wss://mgmt.example.com`), l'agent ajoute `/ws/device` ; si un chemin existe déjà, il le conserve. Pour un Exchange local sans TLS, utilisez `ws://127.0.0.1:8080`.

Pour éviter le jeton dans les arguments du processus, créez un JSON avec `server`, `device_id` et `token` :

```json
{
  "server": "wss://mgmt.example.com",
  "device_id": "lab-router",
  "token": "<设备令牌>"
}
```

Lancez ensuite `remote-agent --config /path/to/config.json`. L'installation et le démarrage automatique sur ordinateur sont décrits dans le [déploiement multiplateforme](/docs/fr/platform-installation.md).

Les WebSocket de `remote-cli` et de `remote-agent` recherchent le proxy dans l'ordre `HTTPS_PROXY` / `https_proxy` → `ALL_PROXY` / `all_proxy` → `HTTP_PROXY` / `http_proxy`, en respectant `NO_PROXY` / `no_proxy`. Les modes sans interface et `--ui` de l'agent partagent le même chemin de connexion. Le proxy doit prendre en charge HTTP CONNECT (SOCKS n'est pas pris en charge) ; l'ALPN WSS annonce uniquement `http/1.1`. Pour les services en arrière-plan, définissez les variables dans l'environnement du service ; voir [Proxy sortant et maintien de connexion](/docs/fr/platform-installation.md#proxy-sortant-et-maintien-de-la-connexion).

Après la connexion de l'appareil :

```bash
remote-cli device list
```

La liste indique son état en ligne.

## Exécuter une commande distante

Le contenu après `--` est transmis à l'appareil et n'est plus analysé par le CLI local :

```bash
remote-cli exec lab-router -- uname -a
```

Le nombre d'arguments après `--` détermine leur interprétation distante :

- **Plusieurs arguments** sont transmis tels quels comme argv, en conservant chaque limite d'argument, comme s'ils étaient saisis directement sur l'appareil. La CLI ajoute les guillemets nécessaires ; pour un appareil Windows, elle suit les règles de PowerShell.
- **Un seul argument** est transmis intégralement au shell de l'appareil pour analyse comme ligne de commande ; tubes, `;`, jokers et variables sont alors utilisables.

```bash
remote-cli exec lab-router -- sh -c 'uname -a; cat /proc/uptime'   # 多个参数，第三个参数完整交给 sh -c
remote-cli exec lab-router -- 'dmesg | tail -20'                    # 一个参数，管道在设备上执行
```

Attention : avec plusieurs arguments, `*` et `$VAR` transmis tels quels par le shell local (fréquent dans PowerShell) sont traités littéralement et ne sont pas développés à distance. Pour laisser l'appareil les développer, utilisez un seul argument, par exemple `-- 'ls /etc/*.conf'`.

L’exécution exec active hold par défaut : le délai est de 3600 secondes par défaut (maximum absolu de 86400 secondes) ; la déconnexion de l'opérateur détache seulement la sortie, sans tuer le travail. Définissez le délai avec `--timeout`, par exemple `remote-cli exec lab-router --timeout 120 -- uname -a` ; `--hold-timeout` peut remplacer le délai hold. `--no-hold` rétablit l'annulation à la déconnexion de l'opérateur, avec un délai par défaut de 60 secondes. À la fin normale d'une commande, son code de sortie devient celui de `remote-cli`.

### Consulter et arrêter les travaux, libérer des emplacements de session

```bash
remote-cli exec-holds lab-router
remote-cli exec-hold-kill lab-router <job_id>
remote-cli exec-hold-tail lab-router <job_id>
remote-cli exec-hold-cat lab-router <job_id>
remote-cli exec-attach lab-router <job_id>
remote-cli sessions lab-router
remote-cli session-kill lab-router <session_id>
```

`exec-holds` liste les travaux exec ainsi que téléchargements, téléversements et requêtes de répertoire en cours, avec `job_id`, `kind`, `status`, `age_secs`, le `session_id` actuel côté appareil s'il existe et un résumé tronqué de la commande ou du chemin. `exec-hold-kill` termine le groupe de processus ou interrompt le transfert grâce à l’identifiant de travail ; les opérations tail, cat et attach sont réservées aux tâches exec.

`sessions` lit directement la table de routage Exchange et affiche `count/limit` ainsi que les identifiants de session côté appareil. `session-kill` utilise cet identifiant **côté appareil**, envoie une annulation et libère immédiatement l'emplacement Exchange, même sans réponse de l'appareil. Aucune des deux commandes ne crée de session supplémentaire ni ne consomme d'emplacement concurrent ; elles conviennent aux sessions bloquées lorsque la limite est atteinte. Les comptes en lecture seule ne peuvent pas les utiliser.

Une expiration exec termine tout le groupe de processus ; la vidange de sortie et l'envoi du message final sont aussi bornés dans le temps. À la limite de concurrence, Exchange récupère d'abord les routes ayant perdu leur opérateur ou dépassé leur échéance, puis tente la nouvelle session : pour exec, délai réel plus 15 secondes de grâce ; pour les transferts, 3600 secondes plus 15 secondes (l'appareil applique aussi 30 secondes d'inactivité) ; pour les autres sessions, 24 heures. Avant son échéance, un exec hold n'est pas tué pour la seule déconnexion de l'opérateur : celle-ci reste un détachement. Un `session-kill` explicite ou le dépassement d'échéance annule le processus hold.

## Ouvrir un shell

```bash
remote-cli shell lab-router
```

Il s'agit d'une session PTY sur l'appareil, pas de SSH. Quitter le shell termine cette session.

## Autres accès

- Console navigateur : [Console Web](/docs/fr/web-console-and-notifications.md)
- Console mobile : [Client mobile](/docs/fr/platform-installation.md)
- APK Agent Android : [APK Android autonome](/docs/fr/platform-installation.md#apk-android-autonome)
- QR codes, codes à six chiffres et comptes : [Initialisation et appairage](/docs/fr/pairing-and-enrollment.md)
- Mise à jour du CLI et de l'agent : [Mise à jour automatique](/docs/fr/self-update.md)

## Chiffrement de bout en bout (sessions scellées)

`remote-cli exec <设备> -- <命令>` et `remote-cli shell <设备>` utilisent des sessions scellées de bout en bout, sans paramètre supplémentaire. Exchange ne transmet que du contenu chiffré et ne voit ni commandes, ni sorties, ni contenu du terminal. L’appareil ne fait confiance qu’à la racine de l’espace de travail (clé du superadministrateur, générée automatiquement à sa connexion) et aux autorisations signées par cette racine ; le client racine délivre automatiquement les autorisations aux membres selon leur rôle de compte. La configuration initiale unique est décrite dans les [sessions scellées de bout en bout](/docs/fr/sealed-sessions.md).

Toutes les sessions d’appareil de la CLI utilisent exclusivement le scellement de bout en bout, sans paramètre supplémentaire. L’absence d’informations sur les capacités de l’appareil ou l’échec de la négociation scellée ne provoque aucun passage en clair. La connexion directe LAN et les opérations du navigateur imposent les mêmes exigences de scellement.

## Tâches persistantes en arrière-plan

Les Agents annonçant `tasks` exécutent des opérations ou des DAG déclaratifs sur l’appareil. Le travail continue après la déconnexion. La reconnexion permet de consulter la progression, la sortie et les artefacts. Un redémarrage marque le travail inachevé `interrupted`, sans répétition automatique.

La création exige des droits scellés `manage/owner`. Les formulaires proposent dépendances, conditions fixes, références JSON Pointer aux ancêtres, politique d’échec et jusqu’à cinq réessais explicites. Les réessais peuvent répéter les effets ; l’annulation ne les inverse pas. Web et mobile proposent formulaires et import/export JSON. Les interfaces locales de bureau, Android, navigateur et LuCI offrent historique, sortie, annulation et suppression.

Consultez d’abord le catalogue des opérations de l’appareil. Préparez les fichiers avant la création. Valeurs par défaut : 30 jours, 1000 tâches, 64 MiB au total, 8 MiB de texte par tâche, quatre étapes parallèles (deux sur OpenWrt), délai de 30 minutes par étape extensible à 24 heures. Les anciens Agents n’affichent pas cette entrée.
```sh
remote-cli task DEVICE operations
remote-cli task DEVICE create pipeline.json --wait
remote-cli task DEVICE list
remote-cli task DEVICE get TASK_ID
remote-cli task DEVICE logs TASK_ID --offset 0
remote-cli task DEVICE cancel TASK_ID
remote-cli task DEVICE upload ./input.bin
remote-cli task DEVICE download TASK_ID STEP.artifact ./result.json
remote-cli task DEVICE delete TASK_ID
```

## Services supervisés

Le mode Service de Task supervise des commandes natives au premier plan avec état souhaité persistant, règles de redémarrage, délai exponentiel, limite de démarrages et reprise après redémarrage de l’Agent. Une définition est arrêtée par défaut. Arrêtez et attendez avant toute modification ou suppression. Une autorisation expirée ou révoquée arrête le service. Les DAG ordinaires ne sont pas rejoués. Gestion sur Web, mobile, bureau et Android ; configuration LuCI via Console ou CLI. Les Agents de navigateur ne supervisent pas les processus système.

Utilisez command.command ou command.argv avec cwd/env, restart (never/on_failure/always), start_secs, stop_grace_secs, backoff_secs, max_backoff_secs, restart_window_secs et max_starts. Un arrêt propre sous Windows nécessite stop_command ; Unix utilise SIGTERM puis termine l’arbre de processus à la fin du délai. Configurez séparément le lancement de l’Agent au démarrage. service get fournit run_id pour task get/logs.

```sh
remote-cli task DEVICE service put worker.json
remote-cli task DEVICE service list
remote-cli task DEVICE service start worker
remote-cli task DEVICE service get worker
remote-cli task DEVICE service restart worker
remote-cli task DEVICE service stop worker
remote-cli task DEVICE service delete worker
remote-agent task service put worker.json
```