Loctavia CLI

loctavia : la gestion locative Loctavia en ligne de commande, au-dessus de l'API REST /loctavia/api/v1. Pensée pour les humains et les agents : sortie JSON sur demande, authentification sans navigateur (device flow), configuration par variables d'environnement.

Installation

npm install -g @sinoia/loctavia-tools

Mise à jour :

npm update -g @sinoia/loctavia-tools   # ou re-`npm install -g` pour épingler une version

Prérequis : Node.js ≥ 20. Deux binaires sont installés : loctavia (et son alias court lt).

Démarrage rapide

# 1. Se connecter à une instance (device flow, sans manipuler de token)
loctavia login --api https://votre-instance.hubdoc.sinoia.cloud

# 2. Choisir le mandataire (tenant) sur lequel travailler
loctavia mandataires list
loctavia mandataires use <mandataire-id>

# 3. Explorer
loctavia leases list --per-page 10
loctavia properties show <id>
loctavia --json owners list          # JSON brut pour un script/agent

Authentification (device flow, RFC 8628)

loctavia login demande un code à l'instance, ouvre la page de confirmation (ou affiche l'URL si aucun navigateur), puis récupère automatiquement un Personal Access Token de scope read write. Le token est stocké dans ~/.config/loctavia/config.json (permissions 0600).

• loctavia logout supprime le token.
• loctavia whoami affiche l'identité et le mandataire actif.

Multi-tenant : le mandataire

Tous les endpoints (sauf mandataires list) sont scopés à un mandataire. La CLI résout l'identifiant dans cet ordre : --mandataire <id> > LOCTAVIA_MANDATAIRE_ID > mandataire actif persisté (mandataires use). Si tu n'as qu'un seul mandataire, l'API le sélectionne d'office.

Exploration des commandes

L'aide est imbriquée à chaque niveau :

loctavia --help
loctavia leases --help
loctavia billing-runs --help
loctavia billing-runs create --help

Ressources disponibles

| Commande | Actions | Description | |----------|---------|-------------| | mandataires | list, use, current | Tenants accessibles, sélection du tenant actif | | leases | list, show, create | Baux | | properties | list, show, create | Immeubles | | units | list, show, create | Lots | | owners | list, show, create | Propriétaires | | tenants | list, show | Locataires | | mandates | list, show, create | Mandats de gestion | | payments | list, show | Encaissements | | incidents | list, show | Incidents locataires | | journal-entries | list, show | Écritures comptables | | billing-runs | list, show, create, lines, validate, apply, update-line | Quittancements (cycle complet) | | fec-exports | create, download | Exports comptables FEC | | pilotage | block | Escalade des agents opérationnels |

Filtres, tri, pagination (commandes list)

loctavia leases list --filter status_eq=active --sort created_at --direction desc
loctavia owners list --q '{"name_cont":"dupont"}'
loctavia units list --page 2 --per-page 50

Les filtres suivent la syntaxe Ransack (_cont, _eq, _gteq, …).

Créations et mutations (corps JSON)

Les commandes create / update-line acceptent le corps en JSON, ce qui reste fidèle au schéma de l'API et pratique pour un agent :

# inline
loctavia leases create --data '{"unitId":"…","tenantId":"…","startDate":"2025-01-01"}'

# depuis un fichier
loctavia properties create --file ./immeuble.json

# depuis stdin
echo '{"name":"Résidence X"}' | loctavia properties create

Cycle de quittancement

loctavia billing-runs create --data '{"lease_ids":["…"]}'   # lance le calcul (asynchrone)
loctavia billing-runs show <id>                             # poller jusqu'à computed/review
loctavia billing-runs lines <id> --type tenant              # relire les lignes
loctavia billing-runs update-line <id> <lineId> --excluded true
loctavia billing-runs validate <id>
loctavia billing-runs apply <id>

Export FEC

loctavia fec-exports create --fiscal-year 2025 --siren 123456789
loctavia fec-exports download <id> --output ./export.fec

Usage par un agent / en CI (sans interaction)

Tout est pilotable par l'environnement, aucun fichier de config requis :

export LOCTAVIA_API_URL=https://votre-instance.hubdoc.sinoia.cloud
export LOCTAVIA_TOKEN=<personal-access-token>
export LOCTAVIA_MANDATAIRE_ID=<mandataire-id>

loctavia --json leases list --per-page 100

• --json (ou -j) : sortie JSON brute sur stdout ; les messages d'état vont sur stderr, donc loctavia --json … > data.json reste propre.
• Code de sortie non nul en cas d'erreur, avec un message actionnable sur stderr.

Variables d'environnement

| Variable | Rôle | |----------|------| | LOCTAVIA_API_URL | URL de l'instance (sinon config, sinon http://localhost:3000) | | LOCTAVIA_TOKEN | Bearer token (court-circuite login) | | LOCTAVIA_MANDATAIRE_ID | Mandataire actif | | XDG_CONFIG_HOME | Emplacement du fichier de config (défaut ~/.config) |

Développement

npm install
npm run typecheck
npm run dev -- leases --help     # exécuter depuis les sources
npm run bundle                   # → dist/publish/ (cli.js autonome + package.json)

Le client est typé à partir de openapi/specs/loctavia.yaml (corex) via npm run gen:types. Le CLI a sa propre ligne de version (cli/package.json), indépendante du gem : la release est portée par la CI de l'engine loctavia sur un tag dédié cli-vX.Y.Z.