Référence des commandes

L'outil en ligne de commande `cof` expose l'intégralité de l'API REST Coffrify v1 depuis votre terminal. Il s'adresse aux mêmes endpoints (https://api.coffrify.com/v1), utilise les mêmes clés (cof_live_, cof_test_, cof_sandbox_) et respecte les mêmes scopes que l'API. Tout ce que vous pouvez faire en HTTP, vous pouvez le faire avec cof, ce qui en fait l'outil idéal pour les scripts de déploiement, les tâches planifiées et l'exploration interactive. Cette page recense les commandes par domaine, les options globales communes à toutes les commandes, ainsi que des exemples d'automatisation prêts à adapter.

Authentification et environnements

cof lit votre clé depuis la variable d'environnement COFFRIFY_API_KEY, ou depuis l'option --api-key. Le préfixe de la clé détermine l'environnement ciblé : cof_live_ pour la production, cof_test_ pour le mode test, et cof_sandbox_ pour un bac à sable isolé de 24 heures. Les clés restreintes (cof_rk_) limitent les scopes accessibles. Définissez la clé une fois dans votre session, puis enchaînez les commandes.

$ export COFFRIFY_API_KEY="cof_live_…"
$ cof transfers list

Options globales

Ces options s'appliquent à toutes les commandes, quel que soit le domaine. Elles contrôlent l'authentification, le format de sortie et l'idempotence des écritures.

Transferts

Les commandes cof transfers couvrent la création, le listage, la consultation et la suppression de transferts chiffrés. La création accepte un ou plusieurs fichiers : cof calcule leur taille, demande les URL de téléversement à l'API, puis envoie chaque fichier par PUT. Vous récupérez en sortie l'identifiant du transfert, son short_code et son share_url.

$ cof transfers create rapport.pdf annexe.xlsx \
    --expires-in-hours 72 \
    --max-downloads 5 \
    --password \
    --recipient client@exemple.fr \
    --transfer-title "Dossier trimestriel"
 
  transfer  tr_8K2f…
  code      A1B2C3
  status    ready
  share_url https://coffrify.com/t/A1B2C3

La commande list est paginée par curseur. Utilisez --limit (jusqu'à 100) puis suivez le curseur renvoyé tant que la réponse indique qu'il reste des pages. Chaque entrée expose notamment id, short_code, transfer_title, status et expires_at.

# Récupérer l'identifiant du dernier transfert créé, en JSON
ID=$(cof transfers list --limit 1 --json | jq -r '.data[0].id')
cof transfers get "$ID" --json

Coffres et collections

Un coffre (data room) regroupe des fichiers et dossiers derrière un accès contrôlé, avec options de filigrane, de NDA et de liste d'e-mails autorisés. Les collections, plus légères, organisent des éléments sous une URL partageable. cof reflète directement les sous-ressources de l'API (files, folders, items, guests).

Réception (intake)

La réception crée un point de dépôt sécurisé. À la création, l'API renvoie deux secrets : une clé publiable cip_ destinée au navigateur de l'expéditeur, et une clé secrète cof_ réservée à votre serveur. Conservez la clé secrète hors du code client. Les documents déposés se listent ensuite par leur identifiant de réception.

$ cof intakes create --name "Pièces justificatives" --json
{
  "intake": { "id": "ink_3p9…", "name": "Pièces justificatives" },
  "publishable_key": "cip_live_…",
  "secret_key": "cof_live_…"
}
$ cof intakes documents ink_3p9…

Webhooks

Les webhooks notifient votre serveur en temps réel. À la création, la réponse contient le secret de signature whsec_, affiché une seule fois : copiez-le immédiatement. Par défaut, un webhook écoute l'événement transfer.downloaded. Vous pouvez déclencher une livraison de test pour valider votre endpoint avant la mise en production. Un espace est limité à 25 webhooks.

# Créer un webhook sur plusieurs événements et capturer le secret
cof webhooks create \
  --url https://exemple.fr/hooks/coffrify \
  --events transfer.created,transfer.downloaded,request.submitted \
  --json | jq -r '.secret'

Exemple : script de bout en bout

Cet exemple enchaîne les commandes dans un script shell : il crée un transfert, en extrait l'URL de partage et l'identifiant via jq, puis affiche le résultat. L'option --idempotency-key garantit qu'un rejeu accidentel (relance du script, réseau instable) ne crée pas de doublon : un rejeu détecté est signalé par l'en-tête X-Coffrify-Idempotent-Replay: true.

#!/usr/bin/env bash
set -euo pipefail
export COFFRIFY_API_KEY="cof_live_…"
 
KEY="deploy-$(date +%Y%m%d)-rapport"
 
RESP=$(cof transfers create ./rapport.pdf \
  --expires-in-hours 168 \
  --max-downloads 3 \
  --idempotency-key "$KEY" \
  --json)
 
URL=$(echo "$RESP" | jq -r '.share_url')
ID=$(echo "$RESP"  | jq -r '.transfer.id')
 
echo "Transfert $ID prêt : $URL"

Gestion des erreurs en script

cof retourne un code de sortie non nul en cas d'échec, ce qui permet de chaîner sereinement avec set -e. Avec --json, le corps d'erreur suit le format standard de l'API : un objet error contenant code, message et request_id. Citez toujours le request_id lorsque vous contactez le support. Les codes courants sont invalid_api_key, scope_missing, validation_error, not_found, rate_limited et idempotency_conflict.

if ! OUT=$(cof transfers get tr_inexistant --json 2>&1); then
  CODE=$(echo "$OUT" | jq -r '.error.code // "unknown"')
  echo "Échec ($CODE)" >&2
  exit 1
fi