Aller au contenu principal

CLI CWClock

Nous fournissons une CLI OpenSource1 pour CWClock. Vous pouvez l'utiliser pour enregistrer votre temps depuis un terminal, et bien plus encore.

cli

Installation​

Choisissez le mode d'installation adapté à votre système d'exploitation, puis suivez les instructions.

Homebrew​

Première installation :

brew tap cwclock/cwclock https://gitlab.cwcloud.tech/oss/cwclock.git
brew trust --formula cwclock/cwclock/cwclock
brew install cwclock

Mise Ă  jour :

brew update
brew upgrade cwclock

Curl​

Linux​

Linux x86 (64 bits)​
version="1.13.8"
curl -L "https://gitlab.cwcloud.tech/oss/cwclock/-/releases/v${version}/downloads/cwclock/cwclock_${version}_linux_amd64.tar.gz" -o "cwclock_cli.tar.gz"
mkdir cwclock_cli && tar -xf cwclock_cli.tar.gz -C cwclock_cli 
sudo ./cwclock_cli/install.sh

Vérifiez que la version est disponible dans les releases, car seules les 5 dernières builds sont conservées.

Linux arm (64 bits)​
version="1.13.8"
curl -L "https://gitlab.cwcloud.tech/oss/cwclock/-/releases/v${version}/downloads/cwclock/cwclock_${version}_linux_arm64.tar.gz" -o "cwclock_cli.tar.gz" 
mkdir cwclock_cli && tar -xf cwclock_cli.tar.gz -C cwclock_cli 
sudo ./cwclock_cli/install.sh

Vérifiez que la version est disponible dans les releases, car seules les 5 dernières builds sont conservées.

MacOS​

macOS x86/arm (64 bits)​
version="1.13.8"
curl -L "https://gitlab.cwcloud.tech/oss/cwclock/-/releases/v${version}/downloads/cwclock/cwclock_${version}_darwin_all.tar.gz" -o "cwclock_cli.tar.gz"
mkdir cwclock_cli && tar -xf cwclock_cli.tar.gz -C cwclock_cli     
sudo ./cwclock_cli/install.sh

Vérifiez que la version est disponible dans les releases, car seules les 5 dernières builds sont conservées.

Windows​

Téléchargement direct​

Vous pouvez directement télécharger depuis ici. Choisissez la bonne architecture (amd64 ou arm64), téléchargez, décompressez et vous trouverez un fichier exe à l'intérieur.

Windows x86 (64 bits) avec Powershell​

$version = "1.13.8"
$user = "YOUR_USER"
cd "C:\Users\${user}"
Invoke-WebRequest -Uri "https://gitlab.cwcloud.tech/oss/cwclock/-/releases/v${version}/downloads/cwclock/cwclock_${version}_windows_amd64.zip" -OutFile "cwclock_cli.zip"
Expand-Archive -Path "cwclock_cli.zip" -DestinationPath "cwclock_cli" -Force
Set-Location "cwclock_cli"
.\cwclock.exe

Vérifiez que la version est disponible dans les releases, car seules les 5 dernières builds sont conservées.

Windows arm (64 bits) avec Powershell​

$version = "1.13.8"
$user = "YOUR_USER"
cd "C:\Users\${user}"
Invoke-WebRequest -Uri "https://gitlab.cwcloud.tech/oss/cwclock/-/releases/v${version}/downloads/cwclock/cwclock_${version}_windows_arm64.zip" -OutFile "cwclock_cli.zip"
Expand-Archive -Path "cwclock_cli.zip" -DestinationPath "cwclock_cli" -Force
Set-Location "cwclock_cli"
.\cwclock.exe

Vérifiez que la version est disponible dans les releases, car seules les 5 dernières builds sont conservées.

Installation de CWClock avec la CLI​

cwclock bootstrap

Flags disponibles :

  • -r ou --release : Nom de release pour le dĂ©ploiement (par dĂ©faut : cwclock)
  • -n ou --namespace : Namespace utilisĂ© pour le dĂ©ploiement (par dĂ©faut : cwclock)
  • -k ou --keep-dir : Conserver le rĂ©pertoire helm local
  • -d ou --recreate-ns : RecrĂ©er le namespace
  • -o ou --openshift : Utiliser la CLI OpenShift au lieu de kubectl
  • -p ou --value : Valeurs pour surcharger la configuration (peut ĂŞtre rĂ©pĂ©tĂ©)
  • --directory : Changer le rĂ©pertoire (utile si vous souhaitez utiliser vos propres templates helm)
  • --kind-cluster : SpĂ©cifier le cluster kind Ă  utiliser (il sera recrĂ©Ă© mĂŞme s'il existe dĂ©jĂ )

Exemple :

cwclock bootstrap -r my-release -n production --value key=value --value values-override.yaml

Ouvrir des tunnels​

cwclock bootstrap pfw

Ouvre des tunnels (ou port forward) vers les différents services. Vous pouvez surcharger la configuration comme ceci :

cwclock bootstrap pfw --config my-pfw-config.yml

Le format YAML de configuration attendu :

---
pfwConfigs:
  - name: "cwclock-api"
    port: 8080
    targetPort: 8080
  - name: "cwclock-ui"
    port: 3000
    targetPort: 3000

Configuration​

cwclock configure
cwclock configure set format pretty
cwclock configure set api_url https://api.cwclock.me
cwclock configure set api_key <your api key>

Remarque : il est aussi possible d'utiliser des variables d'environnement QWCTL_{VAR_NAME} au lieu de ce fichier de configuration. Par exemple, pour le format de sortie, vous pouvez définir la variable QWCTL_FORMAT à json ou pretty.

Organisations​

Lister, créer, mettre à jour et supprimer des organisations.

cwclock organization ls
cwclock organization create --name "Acme Corp" --country FR
cwclock organization update -i <organization id> --name "Nouveau nom"
cwclock organization delete -i <organization id>

Flags disponibles pour create (les mĂŞmes champs existent pour update, tous optionnels dans ce cas) :

  • --name : Nom de l'organisation (requis Ă  la crĂ©ation)
  • --country : Code pays (requis Ă  la crĂ©ation)
  • --address, --city, --postal-code : Champs d'adresse
  • --currency : Code devise
  • --identification-number, --naf, --siren, --siret, --vat-number, --mf : Identifiants d'immatriculation/fiscaux
  • --iban, --bic : CoordonnĂ©es bancaires
  • --accounting-email : Email de comptabilitĂ©, mis en copie sur les emails de facture
  • -f ou --format : Surcharge du format de sortie : pretty ou json

Connexions externes​

Les organisations peuvent envoyer leurs exports planifiés et leurs factures vers un stockage externe (s3, google_drive ou git). Lister, créer ou supprimer les connexions d'une organisation :

cwclock organization connection ls -i <organization id>
cwclock organization connection -i <organization id> --type s3 --bucket-name my-bucket --endpoint https://s3.example.com --access-key <key> --secret-key <secret> --region eu-west-1
cwclock organization connection -i <organization id> --offset 0
  • -i ou --id : ID de l'organisation (requis)
  • --type : Type de connexion Ă  crĂ©er : s3, google_drive ou git
  • --offset : Position de la connexion Ă  supprimer, telle qu'indiquĂ©e par ls (par dĂ©faut -1)
  • --path : Sous-dossier de destination optionnel
  • --flat-directory : Envoyer directement Ă  la racine de destination au lieu d'imbriquer sous YYYY/MM
  • S3 : --bucket-name, --endpoint, --access-key, --secret-key, --region
  • Google Drive : --folder-id, --service-account-base64
  • Git : --repo-url, --username, --password, --ssh-private-key, --ssh-private-key-passphrase

Clients​

Lister, créer, mettre à jour et supprimer les clients d'une organisation.

cwclock client ls
cwclock client create --name "Client A" --country FR --daily-rate 500
cwclock client update -i <client id> --email billing@client.com
cwclock client delete -i <client id>
  • --name : Nom du client (requis Ă  la crĂ©ation)
  • --country : Code pays (requis Ă  la crĂ©ation)
  • --email, --contact-name, --address, --city, --postal-code : CoordonnĂ©es
  • --daily-rate, --hours-per-day : Valeurs de facturation par dĂ©faut (les heures par jour valent 7 cĂ´tĂ© serveur si omis)
  • --vat-rate, --vat-number, --vat-discharge-motive : Paramètres de TVA (le taux de TVA vaut 20 cĂ´tĂ© serveur si omis)
  • --identification-number, --naf, --mf, --siren, --siret : Identifiants d'immatriculation
  • --purchase-order : Bon de commande
  • --invoice-emails : Emails destinataires des factures, sĂ©parĂ©s par virgule/point-virgule
  • --send-reports-with-invoice : Joindre les rapports de temps aux emails de facture envoyĂ©s Ă  ce client
  • -o ou --org : ID ou nom de l'organisation (surcharge le org_id configurĂ©)
  • -f ou --format : Surcharge du format de sortie : pretty ou json

Projets​

Lister, créer, mettre à jour et supprimer les projets d'un client.

cwclock project ls
cwclock project ls -c <client id ou nom>
cwclock project create --name "Refonte du site" -c <client id ou nom> --daily-rate 450 --color "#3b82f6"
cwclock project update -i <project id> --subdivisions "backend,frontend"
cwclock project delete -i <project id>
  • -c ou --client : ID ou nom du client (requis Ă  la crĂ©ation ; rĂ©assigne le projet en mise Ă  jour ; filtre sur ls)
  • --name : Nom du projet (requis Ă  la crĂ©ation)
  • --daily-rate : Taux journalier
  • --color : Couleur du projet
  • --subdivisions : Liste de subdivisions sĂ©parĂ©es par des virgules
  • -o ou --org : ID ou nom de l'organisation (surcharge le org_id configurĂ©)
  • -f ou --format : Surcharge du format de sortie : pretty ou json

Enregistrements de temps​

Suivez votre temps avec un chronomètre, ou enregistrez directement une plage horaire.

cwclock record start -p <project id ou nom>
cwclock record stop
cwclock record create --begin "now()-1h" --end "now()" -p <project id>
cwclock record create --from 2024-01-15T09:00:00 --to 2024-01-15T12:00:00 -t 'réunion' -p <project id>
cwclock record create --all-day --begin 2024-01-15 -p <project id>
cwclock record ls
cwclock record ls --max 50
cwclock record delete -i <record id>
  • -p ou --project : ID ou nom du projet (requis pour start/create) ; son client est dĂ©duit automatiquement sauf si -c/--client le surcharge
  • -t ou --text : Description de l'enregistrement (par dĂ©faut, le nom du projet ; sur stop, surcharge le texte donnĂ© au start)
  • --begin/--from, --end/--to : Plage pour create — ISO-8601 (une date YYYY-MM-DD seule vaut 00:00:00/23:59:59), ou une expression du style now()/now()-1h/now()-1d
  • --all-day : CrĂ©er un enregistrement journĂ©e entière pour la date donnĂ©e par --begin/--from, au lieu d'une plage prĂ©cise (--end/--to doit ĂŞtre omis)
  • --max : Nombre maximum d'enregistrements Ă  afficher avec ls (par dĂ©faut 10)
  • -o ou --org : ID ou nom de l'organisation (surcharge le org_id configurĂ©)
  • -f ou --format : Surcharge du format de sortie : pretty ou json

Export​

Téléchargez un rapport de temps synthétique ou détaillé au format PDF ou CSV sur une plage de dates, filtré éventuellement sur un ou plusieurs clients/projets (tout est inclus si omis).

cwclock export --client <client uuid> --begin 2024-01-15T09:00:00 --end 2024-01-15T12:00:00
cwclock export --type detailed --file-format csv --client <id1> --client <id2> --project <id3> --begin now()-30d --end "now()"
  • --type : Type de rapport : summary ou detailed (par dĂ©faut summary)
  • --file-format : Format de fichier : pdf ou csv (par dĂ©faut pdf)
  • -c ou --client : Filtre par client (id ou nom, rĂ©pĂ©table ; tous les clients sont inclus si omis)
  • -p ou --project : Filtre par projet (id ou nom, rĂ©pĂ©table ; tous les projets sont inclus si omis)
  • --begin : Date/heure de dĂ©but : ISO-8601 ou expression du style now()/now()-1h/now()-1d (requis)
  • --end/--to : Date/heure de fin : ISO-8601 ou expression du style now()/now()-1h/now()-1d
  • -o ou --output : Chemin du fichier de sortie (par dĂ©faut, le nom fourni par le serveur, ou <type>.<file-format> dans le rĂ©pertoire courant)
  • --org : ID ou nom de l'organisation (surcharge le org_id configurĂ©)

Factures​

Prévisualisez, générez, envoyez, téléversez et supprimez des factures clients.

cwclock invoice preview --client <client uuid> --begin 2024-01-15T09:00:00 --end 2024-01-15T12:00:00
cwclock invoice generate --client <client uuid> --begin 2024-01-15T09:00:00 --to 2024-01-15T12:00:00
cwclock invoice send -i <invoice id>
cwclock invoice upload -i <invoice id>
cwclock invoice delete -i <invoice id>

Remarques :

  • preview gĂ©nère le PDF sans rien sauvegarder cĂ´tĂ© serveur, ce qui permet de le vĂ©rifier avant de gĂ©nĂ©rer la vraie facture ; generate le sauvegarde sous son propre numĂ©ro de facture et renvoie le mĂŞme PDF en tĂ©lĂ©chargement
  • -c ou --client : ID ou nom du client, pour preview/generate (requis)
  • -p ou --project : ID ou nom du projet Ă  inclure, pour preview/generate (rĂ©pĂ©table ; vide = tous les projets)
  • --begin, --end/--to : Plage de dates, pour preview/generate (mĂŞmes formats que pour l'export)
  • -o ou --output : Chemin du fichier de sortie, pour preview/generate (par dĂ©faut, le nom fourni par le serveur dans le rĂ©pertoire courant)
  • send envoie par email le PDF d'une facture dĂ©jĂ  gĂ©nĂ©rĂ©e aux destinataires du client
  • upload renvoie le PDF d'une facture dĂ©jĂ  gĂ©nĂ©rĂ©e vers toutes les connexions externes de son organisation (par exemple après correction des identifiants d'une connexion)
  • -i ou --id : ID ou numĂ©ro de facture, pour delete/send/upload
  • --org : ID ou nom de l'organisation (surcharge le org_id configurĂ©)

Jobs d'export planifiés​

Automatisez des exports récurrents (et, en option, l'envoi de factures) selon une planification cron.

cwclock job ls
cwclock job create --name "Synthèse mensuelle" --cron "0 6 1 * *" --time-period "now()-30d" --report-types summary-pdf,detailed-csv --type email --to accounting@client.com
cwclock job update -i <job id> --enabled=false
cwclock job run -i <job id>
cwclock job delete -i <job id>
  • --name : Nom du job (requis Ă  la crĂ©ation)
  • --cron : Expression cron (requise Ă  la crĂ©ation)
  • --time-period : PĂ©riode couverte par chaque exĂ©cution (requise Ă  la crĂ©ation), ex. : now(), now()-1d, now()-1h
  • --report-types : Types de rapports sĂ©parĂ©s par des virgules (requis Ă  la crĂ©ation) : summary-pdf, summary-csv, detailed-pdf, detailed-csv, unpaid-invoices, all-invoices
  • --enabled : Si le job est activĂ© (par dĂ©faut true)
  • --include-financial : Inclure les montants financiers dans les rapports exportĂ©s
  • -c ou --client, -p ou --project : ID ou nom du client/projet Ă  inclure (rĂ©pĂ©table ; vide = tous)
  • --type : Type de la première cible Ă  la create : email (par dĂ©faut), s3, google_drive ou git — voir les flags de cible ci-dessous
  • -o ou --org : ID ou nom de l'organisation (surcharge le org_id configurĂ©)
  • -f ou --format : Surcharge du format de sortie : pretty ou json

run exécute le job immédiatement, en dehors de sa planification cron habituelle, en utilisant le même chemin de livraison qu'une exécution planifiée. update ne modifie que les flags passés, y compris la sélection des rapports/cibles — gérez les cibles elles-mêmes avec job target.

Cibles​

Un job peut livrer vers plusieurs cibles (email, S3, Google Drive ou Git). Listez, ajoutez ou supprimez-les :

cwclock job target ls -i <job id>
cwclock job target create -i <job id> --type s3 --bucket-name my-bucket --endpoint https://s3.example.com --access-key <key> --secret-key <secret> --region eu-west-1
cwclock job target delete -i <job id> --offset 0
  • -i ou --id : ID du job (requis)
  • --type : Type de cible : email (par dĂ©faut), s3, google_drive ou git
  • --offset : Position de la cible Ă  supprimer, telle qu'indiquĂ©e par ls (requis pour delete)
  • Email : --to, --cc (sĂ©parĂ©s par virgule/point-virgule)
  • S3 : --bucket-name, --endpoint, --access-key, --secret-key, --region
  • Google Drive : --folder-id, --service-account-base64
  • Git : --repo-url, --username, --password, --ssh-private-key, --ssh-private-key-passphrase
  • --path : Sous-dossier de destination optionnel (cible s3/google_drive/git)

Administration (superutilisateur)​

Commandes réservées au superutilisateur pour gérer toutes les organisations et tous les utilisateurs, sans condition d'appartenance.

cwclock admin organization ls
cwclock admin organization transfert -i <organization id> --owner <user id>
cwclock admin organization delete -i <organization id>
cwclock admin user ls
cwclock admin user update -i <user id ou email> --role confirmed
cwclock admin user set-role superuser -i <user id ou email>
cwclock admin user delete -i <user id ou email>
  • admin organization transfert transfère la propriĂ©tĂ© de n'importe quelle organisation Ă  un autre utilisateur via --owner <user id>
  • admin user set-role <role> dĂ©finit le rĂ´le global d'un utilisateur : superuser, confirmed, disabled ou ban
  • admin user update accepte --email, --name, --surname, --password et --role, en ne modifiant que les flags passĂ©s
  • -f ou --format : Surcharge du format de sortie : pretty ou json

Métriques​

Récupérer toutes les métriques disponibles (depuis l'URL prometheus /v1/metrics de l'API) avec :

cwclock metrics ls

Récupérer une métrique particulière avec :

cwclock metrics get <metric_name>
cwclock metrics get <metric_name>

Remarques :

  • Le wildcard * est pris en charge pour rĂ©cupĂ©rer toutes les mĂ©triques qui commencent par une chaĂ®ne particulière (ex. : cwclock metrics get "cwclock_projects_*" pour rĂ©cupĂ©rer toutes les mĂ©triques dont le nom commence par cwclock_projects_)
  • Le filtrage par labels est aussi pris en charge avec le flag --filter (ex. : cwclock metrics get "cwclock_task_*" --filter "organization_id=xxxxx-xxxxx-xxxxx-xxxxx" pour rĂ©cupĂ©rer les mĂ©triques qui commencent par cwclock_task_ avec le label kind Ă©gal Ă  xxxxx-xxxxx-xxxxx-xxxxx)

IA MCP et agents​

Créer un serveur MCP​

cwclock ai mcp
cwclock ai mcp -l 127.0.0.1 -p 8080 -e /mcp

Créer un agent appelant le serveur MCP​

cwclock ai agent -p "List the indexes"
cwclock ai agent -p "Search *" -s "http://127.0.0.1:8080/mcp" --provider anthropic

Remarque : les fournisseurs disponibles sont anthropic, openai, deepseek ou openrouter. Pour le moment, vous pouvez configurer vos clés comme ceci :

cwclock configure set openai_api_key "your_key"
cwclock configure set anthropic_api_key "your_key"
cwclock configure set openrouter_api_key "your_key"
cwclock configure set deepseek_api_key "your_key"
cwclock configure set gemini_api_key "your_key"
cwclock configure set mistral_api_key "your_key"

Vous pouvez aussi utiliser des variables d'environnement :

export CWCLOCK_OPENAI_API_KEY="your_key"
export CWCLOCK_ANTHROPIC_API_KEY="your_key"
export CWCLOCK_OPENROUTER_API_KEY="your_key"
export CWCLOCK_DEEPSEEK_API_KEY="your_key"
export CWCLOCK_GEMINI_API_KEY="your_key"
export CWCLOCK_MISTRAL_API_KEY="your_key"

Remarque : vous pouvez aussi utiliser le mode interactif pour créer votre agent avec le flag -i ou --interactive :

cwclock ai agent -i

Créer un agent web​

Vous pouvez aussi utiliser un mode serveur web pour interroger votre agent via des requĂŞtes HTTP POST au lieu de la CLI :

cwclock ai web-agent -a 0.0.0.0 -p 8081

Le chemin / peut être configuré comme un adaptateur IA externe et vous pourrez l'utiliser dans le chat de CWCloud :

ai-cwcloud-chat

Ou faire des fonctions/cron job serverless avec CWCloud Ă©galement :

ai-cwcloud-faas

Ou bien l'utiliser directement avec Aristochat.

Le chemin /gitlab comme un webhook GitLab si vous définissez les configurations suivantes :

cwclock configure set gitlab_base_url "https://gitlab.cwcloud.tech"
cwclock configure set gitlab_token "your_gitlab_token"
cwclock configure set gitlab_webhook_secret "your webhook secret"

Ou avec les variables d'environnement suivantes :

export CWCLOCK_GITLAB_BASE_URL="https://gitlab.cwcloud.tech"
export CWCLOCK_GITLAB_TOKEN="your_gitlab_token"
export CWCLOCK_GITLAB_WEBHOOK_SECRET="your webhook secret"

Lister tous les outils MCP disponibles​

cwclock ai agent -p "list_mcp_dynamic_tools"

Remarque : un serveur MCP cwclock doit être en cours d'exécution pour que cette commande fonctionne.

Footnotes​

  1. Sous licence MIT, les sources sont disponibles ici. ↩