@mdemb/colis

Envoyez d’un terminal. Suivez la réponse.

colis envoyer dépose un fichier et affiche son code ; colis statut dit si votre client l’a ouvert, validé ou renvoyé pour corrections. Les commandes sont en français, et put, get, rm et doctor restent des alias.

Référence CLI La page de livraison Source

$ colis envoyer ./maquette-v2.pdf
maquette-v2.pdf · 1.8 MB · expires in 1 day
K7QP2M4X

$ CODE=$(colis envoyer ./export.zip)        # the code on stdout, the rest on stderr
$ tar cz ./site | colis envoyer - --name site.tar.gz

$ colis statut K7QP2M4X
ouvert
envoyé  2026-09-22 10:00
ouvert  2026-09-22 11:00
answer  not yet

$ colis statut K7QP2M4X | head -1           # the state alone, for a script
ouvert

$ colis envoyer ./maquette-v3.pdf --remplace K7QP2M4X   # changes asked: same code, same link
maquette-v3.pdf · 1.9 MB · expires in 1 day
Version 2 envoyée sur K7QP2M4X
K7QP2M4X

Installation

Une commande npm, rien à configurer.

`npm i -g @mdemb/colis` installe la commande `colis`. Node 20 ou plus. Sans rien configurer, `colis envoyer` passe par le service public de colis — fichiers de 100 Mo au plus, gardés 24 h au plus, 20 envois par heure depuis une même adresse — et `colis statut` suit la livraison. Pour votre propre stockage, configurez un bucket ou votre propre page de livraison.

npm i -g @mdemb/colis

# nothing to configure: the public colis service
colis envoyer ./maquette.pdf
colis statut <CODE>

envoyer et statut

Le code sur stdout, la réponse à la demande.

Avec votre page de livraison, chaque colis a son accusé de réception. statut affiche l’état en première ligne, puis chaque étape avec son heure, et le commentaire du client en dernier.

statut interroge une page de livraison : l’accusé est tenu par elle, pas par le bucket. Sans rien configurer, c’est le service public. Avec un bucket et sans --remote, statut le dit, indique si le fichier est encore là, et sort en erreur. --json donne l’accusé complet, et un colis protégé demande aussi son mot de passe, avec --token.

recevoir et annuler

$ colis recevoir k7qp-2m4x                 # lower case, a dash: still found
Wrote /home/you/maquette-v2.pdf · 1.8 MB

$ colis recevoir K7QP2M4X -o - | less       # or to stdout
$ colis annuler K7QP2M4X                    # burn it before it expires
Burned K7QP2M4X

init et verifier

La commande à lancer en premier.

Pointée vers un serveur, verifier fait un vrai aller-retour. Pointée vers un bucket, elle effectue les opérations dont colis a besoin et rapporte ce qui s’est passé, règle de cycle de vie comprise. La sonde est supprimée avant la fin.

un fichier de départ pour votre page de livraison

$ colis init --provider remote
Wrote /home/you/client-acme/colis.config.json

Point "remote" at your deployment of the transfer routes.
Put its token in .env as COLIS_TOKEN. This machine needs no S3 credentials at all.
Run `colis verifier` — it performs the operations colis needs and reports what happened.

et la vérification qui prouve qu’elle répond

$ colis verifier
Using /home/you/client-acme/colis.config.json
✓ Server: https://livraison.example.com/api/transfers answered
✓ Create, read, delete: round-tripped code 8WTXQC8R

Ready to store transfers.

directement sur un bucket

$ colis -p r2 verifier
Using /home/you/client-acme/colis.config.json (profile "r2")
✓ Configuration: bucket "livraisons", region "auto"
✓ Credentials: resolved, key ends in 1a2b
✓ Bucket reachable: HeadBucket succeeded
✓ Write, read, delete: round-tripped a probe object
! Expiry cleanup: no enabled expiration rule
  → Add an S3 lifecycle rule that expires objects under this bucket after a day or
    two. Without it, expired transfers stay stored and billed.

1 check(s) failed.

verifier sort en erreur quand une vérification échoue : c’est un test de fumée de déploiement tout trouvé. init --provider écrit un fichier de départ pour aws, r2, minio, scaleway, wasabi ou remote, avec des références ${VAR} plutôt que des secrets.

Configuration

Des réglages à versionner, des clés à garder pour soi.

${VAR} est lu dans l’environnement, et envFile désigne un fichier à charger d’abord sans écraser ce que le shell a déjà défini. Les profils rangent plusieurs configurations dans un fichier. Une option l’emporte sur une variable, qui l’emporte sur le fichier.

colis.config.json

{
  "envFile": ".env",
  "profiles": {
    "livraison": {
      "remote": "https://livraison.example.com/api/transfers",
      "token": "${COLIS_TOKEN}"
    },
    "r2": {
      "bucket": "livraisons",
      "region": "auto",
      "endpoint": "https://${R2_ACCOUNT_ID}.r2.cloudflarestorage.com",
      "expiresIn": "7d",
      "credentials": { "accessKeyId": "${R2_ACCESS_KEY_ID}", "secretAccessKey": "${R2_SECRET_ACCESS_KEY}" }
    },
    "local": { "bucket": "livraisons", "endpoint": "http://localhost:9000" }
  }
}

$ colis -p livraison envoyer ./maquette-v2.pdf   # through your delivery page
$ colis -p livraison statut K7QP2M4X
$ colis -p local verifier                       # against a MinIO container

$ colis config                   # which value won, and where it came from

Le fichier est cherché depuis le dossier courant en remontant, puis dans ~/.config/colis/config.json. colis config affiche quelle valeur a gagné et d’où elle vient ; il masque l’identifiant de clé et n’affiche jamais le secret ni le jeton.

Livrer depuis la CI

Référence

Sept commandes, une douzaine d’options.

Commandes

envoyer <fichier>: Stocke un fichier et affiche le code à transmettre. « - » lit stdin
recevoir <code>: Récupère ce que désigne un code : sous son nom d’origine, vers -o, ou sur stdout
statut <code>: Suivi de livraison : envoyé, ouvert, validé ou à corriger. Demande --remote
annuler <code>: Supprime un code
verifier: Vérifie que cette configuration peut vraiment stocker des transferts. Sort en erreur si un contrôle échoue
init: Écrit un colis.config.json de départ pour aws, r2, minio, scaleway, wasabi ou remote
config: Affiche la configuration résolue, et d’où vient chaque valeur
put, get, rm, doctor: Les noms anglais, conservés comme alias

Options

-c, --config: Fichier de configuration à lire
-p, --profile: Profil à utiliser dans ce fichier
--env-file: Lit d’abord des paires CLÉ=valeur depuis ce fichier
--bucket, --prefix, --region, --endpoint: Réglages du bucket, prioritaires sur le fichier et l’environnement
--expires-in: 3600, 30m, 24h, 7d, ou never
--remote, --token: Passer par un serveur colis plutôt que par S3, avec son mot de passe
--name: Nom de fichier sous lequel stocker le transfert
-o, --output: Où recevoir écrit. « - » pour stdout
--json: Sortie lisible par une machine, pour les scripts et pour verifier en CI
--provider, --force: Quel fichier de départ init écrit, et s’il peut écraser

Sinon, la configuration vient des variables d’environnement : COLIS_REMOTE, COLIS_TOKEN, COLIS_BUCKET, COLIS_ENDPOINT et les identifiants AWS habituels. Les arguments sont lus par parseArgs de node:util : rien d’autre à installer.

Vous envoyez. Ils valident. Vous le savez.

Votre stockage, une page de livraison à votre nom, un webhook à chaque étape. Rien d’hébergé chez un tiers.

Essayer la démo Déployer la page de livraison GitHub