Configuration

dokos a besoin de trois informations pour dialoguer avec un site : son URL, une clé d'API et un secret d'API. Plusieurs façons de les fournir coexistent.

Obtenir une clé et un secret d'API

1. Dans Dokos, ouvrez la fiche de l'utilisateur qui servira à la CLI.
2. Dans la section Accès API, cliquez sur Générer des clés.
3. Copiez le secret. Il n'est affiché qu'une seule fois.

Les commandes agissent avec les rôles et les permissions de cet utilisateur.

Ordre de résolution des identifiants

dokos résout les identifiants dans cet ordre :

1. L'option -s / --site <nom> : elle cible un site enregistré pour une seule commande, sans changer le site actif.
2. Les variables d'environnement DOKOS_URL, DOKOS_API_KEY et DOKOS_API_SECRET, si les trois sont définies.
3. Le site actif enregistré dans ~/.config/dokos/config.json.
4. Sinon, la commande s'arrête avec un message qui renvoie vers dokos configure.

A. Site distant, en interactif

dokos configure

L'assistant demande l'URL, la clé et le secret d'API, vérifie la connexion, puis enregistre le site.

B. Bench local, en automatique

Si un bench Dokos tourne sur la même machine, dokos le détecte et émet les clés pour vous :

dokos use-site                                # depuis l'intérieur du bench (ou --bench <chemin>)
dokos use-site dev.localhost                  # cibler un site précis
dokos use-site dev.localhost --user jane@example.com   # agir en tant qu'un utilisateur donné

dokos remonte jusqu'à la racine du bench, choisit ou demande le site, puis demande pour quel utilisateur émettre les clés (par défaut Administrator). Les clés héritent des rôles et permissions de cet utilisateur : ce sont ses droits qui gouvernent ce que les commandes peuvent lire et écrire.

dokos setup est un assistant guidé autour de use-site. Ces deux commandes appellent bench : elles fonctionnent sous Linux et macOS seulement.

C. Site distant, en non interactif

Pratique pour les scripts et les agents :

dokos add-site akyer \
  --url https://akyer.dokos.cloud \
  --api-key CLE --api-secret SECRET

Plusieurs sites

dokos configure --name dashboard     # enregistrer un site distant sous un nom
dokos use-site --name staging        # relier un bench local sous un nom
dokos sites                          # lister les sites et afficher le site actif
dokos use dashboard                  # changer de site actif (persistant)
dokos -s staging get-list "Task"     # cibler un site pour une seule commande
dokos remove-site staging            # oublier un site (demande confirmation, ou --yes)

Protéger un site en lecture seule

Un site en lecture seule refuse toute écriture avant que la requête ne quitte votre machine. Le contrôle se fait dans la CLI, sur la méthode HTTP. C'est une cible sûre pour un agent exploratoire.

dokos sites --read-only prod    # passer un site enregistré en lecture seule
dokos sites --writable prod     # revenir en lecture-écriture
DOKOS_READ_ONLY=1 dokos …       # forcer la lecture seule pour une commande

Les rapports restent disponibles sur un site en lecture seule.

Où sont stockés les identifiants

Le fichier ~/.config/dokos/config.json (droits 0600) contient le registre des sites :

{
  "sites": {
    "mysite": {
      "url": "https://votre-site.dokos.cloud",
      "api_key": "...",
      "read_only": true
    }
  },
  "active_site": "mysite",
  "gitlab_token": "..."
}

Le secret d'API n'est pas dans ce fichier. Il est rangé dans le trousseau du système d'exploitation (service dokos-cli, une entrée par site). Sans trousseau disponible (conteneur, intégration continue, session SSH), le secret reste dans le fichier, en droits 0600. DOKOS_PLAINTEXT_SECRETS=1 impose ce mode fichier.

Variables d'environnement

Éditer une clé de configuration

dokos config list                    # toutes les clés, valeurs masquées, et leur source
dokos config set url https://demo.dokos.cloud
dokos config get api_secret --show-secrets
dokos config unset gitlab_token
dokos config path                    # emplacement du fichier

Les clés modifiables sont url, api_key, api_secret et gitlab_token. La colonne Source indique env:<VARIABLE> si une variable d'environnement prend le dessus, file si la valeur vient du fichier, ou not set.

Cache du catalogue

dokos sync télécharge la liste des DocTypes et des rapports dans deux fichiers Markdown lisibles par un LLM :

~/.config/dokos/doctypes.md
~/.config/dokos/reports.md

Dans doctypes.md, (S) signale un DocType Single, (T) une table enfant et (Sub) un DocType validable.

Le cache est régénéré automatiquement s'il est absent ou vieux de plus de 30 jours. Relancez dokos sync après une mise à jour des applications Dokos.