Version de développement

Cette documentation décrit la version « next » (develop), non encore publiée. Pour la version stable, basculez sur « v5 » dans l'en-tête.

Dokos CLI

Commandes

Référence des commandes Dokos CLI (lecture, rapports, schéma, écriture, envoi de fichiers, appel de méthodes serveur) et des trois modes de sortie.

Toutes les commandes s'exécutent sur le site actif, ou sur le site indiqué par -s / --site <nom> (voir la configuration).

Modes de sortie

La sortie standard contient seulement les données. Les erreurs, la progression et les suggestions vont sur la sortie d'erreur. Vous pouvez donc toujours rediriger la sortie vers un autre outil.

Option	Sortie	Quand l'utiliser
(aucune)	Tableau dans un terminal, JSON brut si la sortie est redirigée	lecture par un humain, ou `\| jq`
`--json`	`{"data": [...], "next": [...]}` avec des commandes de suivi suggérées	enchaînement d'outils, usage par un agent
`--quiet`	JSON brut, même dans un terminal	forcer le JSON brut

dokos get-list "Item" | jq '.[].item_code'

Codes de sortie : 0 succès, 1 échec, 2 erreur d'utilisation.

Une erreur affiche le message du serveur, puis une ligne Hint: qui indique la commande utile :

$ dokos insert '{"doctype":"Sales Invoice"}'
Error: Customer is mandatory
Hint: See which fields are required: dokos meta get "<DocType>"

Les noms de DocTypes et de rapports sont les noms techniques, en anglais, et sensibles à la casse : "Sales Invoice", pas "Facture de vente". Lancez dokos sync pour obtenir la liste exacte.

Lecture

Commande	Rôle
`dokos get-list <DocType>`	Liste paginée de documents (`--fields`, `--filters`, `--order-by`, `--limit` = 20 par défaut, `--start`)
`dokos get <DocType> [<nom>]`	Un document complet, par son nom ou par `--filters` (premier résultat)
`dokos get-count <DocType>`	Nombre de documents (avec `--filters`)
`dokos get-value <DocType> <champ>`	Un ou plusieurs champs d'un document
`dokos get-single-value <DocType> <champ>`	Un champ d'un DocType Single (paramètres globaux)

Les filtres ont deux formes selon la commande :

liste de triplets pour get-list et get-count : '[["status","=","Draft"]]' ;
objet pour get et les filtres de rapport : '{"status":"Draft"}'.

dokos get-list "Sales Invoice" \
  --filters '[["status","=","Overdue"]]' \
  --fields '["name","customer","grand_total"]' \
  --order-by 'grand_total desc' --limit 10 --json

dokos get "User" "Administrator"
dokos get-single-value "System Settings" "time_zone"

Avec --json, le tableau next contient la commande prête à l'emploi pour la page suivante.

Rapports

Commande	Rôle
`dokos run-report <nom>`	Exécuter un rapport et renvoyer ses lignes (`--filters`, `--fresh` pour ignorer le cache)
`dokos report list`	Lister les rapports actifs (`--ref-doctype`, `--type`, `--limit` = 50 par défaut)
`dokos report get <nom>`	Définition d'un rapport : type, DocType de référence, requête, colonnes
`dokos report run <nom>`	Identique à `run-report`
`dokos report create <nom>`	Créer un Query Report à partir de SQL (`--query`, `--ref-doctype`)

dokos run-report "General Ledger" \
  --filters '{"company":"Dokos SAS","from_date":"2026-01-01","to_date":"2026-12-31"}' --json

Les filtres dépendent du rapport. En cas de doute, lisez sa définition avec dokos report get.

Schéma et permissions

Commande	Rôle
`dokos meta get <DocType>`	Schéma compact : champs (nom, libellé, type, options, obligatoire) et indicateurs
`dokos perms get <DocType>`	Règles de permissions déclarées par rôle

Avant d'écrire, un dokos meta get donne les champs obligatoires et les options des champs Link et Select.

Écriture

Commande	Rôle
`dokos set-value <DocType> <nom> <champ> <valeur>`	Modifier un champ. La valeur est lue en JSON si possible (nombre, booléen)
`dokos insert '<json>'`	Créer un document (l'objet contient `doctype`)
`dokos save '<json>'`	Mettre à jour un document (l'objet contient `doctype` et `name`)
`dokos submit <DocType> <nom>`	Valider un document (statut 0 → 1)
`dokos cancel <DocType> <nom>`	Annuler un document validé (statut 1 → 2)
`dokos amend <DocType> <nom>`	Créer un nouveau brouillon à partir d'un document annulé
`dokos delete <DocType> <nom>`	Supprimer un document. Irréversible
`dokos rename <DocType> <ancien> <nouveau>`	Renommer un document (`--merge` pour fusionner avec un document existant)
`dokos bulk-update '<json>'`	Mettre à jour plusieurs documents en une requête
`dokos upload-file <chemin>`	Envoyer un fichier, et le joindre à un document avec `--doctype`, `--docname`, `--fieldname` (`--private` pour un fichier privé)

Les commandes destructrices (submit, cancel, delete, rename --merge, bulk-update) demandent une confirmation. -y / --yes la passe.

set-value et save envoient la date de dernière modification du document. Si quelqu'un a modifié le document entre-temps, l'écriture est refusée. Relisez le document et recommencez, ou ajoutez --force pour écraser la modification.

Exemple : corriger une facture validée

Exemple fictif. La facture SINV-0001 est validée avec une erreur.

dokos cancel "Sales Invoice" "SINV-0001" -y
dokos amend  "Sales Invoice" "SINV-0001"      # crée un brouillon, par exemple SINV-0001-1
dokos set-value "Sales Invoice" "SINV-0001-1" po_no "PO-42"
dokos submit "Sales Invoice" "SINV-0001-1" -y

Le nom du nouveau brouillon dépend de la série de nommage du site : lisez-le dans la réponse de dokos amend.

Les commandes d'écriture modifient des données réelles. Elles utilisent les droits de l'utilisateur à qui appartiennent la clé et le secret d'API. Sur un site en lecture seule, elles sont refusées avant l'envoi de la requête.

Appel de méthode serveur (RPC)

dokos call invoque une méthode serveur autorisée (@frappe.whitelist) par son chemin :

dokos call frappe.client.get_count --args '{"doctype":"Task"}'

Découverte pour les agents

Chaque commande de données accepte l'option cachée --agent. Elle décrit au format JSON le contrat de la commande : description, arguments, options et pièges. Les agents s'en servent pour se documenter eux-mêmes :

dokos get-list --agent