La ligne de commande bastide

La commande bastide pilote la plateforme depuis un terminal ou un script d'intégration continue : se connecter, lier un dossier à un projet, déployer en suivant le journal en direct, et appeler n'importe quelle opération du registre. Cette page dit comment l'installer, s'y connecter, et ce qu'un script peut attendre de ses sorties.

Installer

npm install -g bastide && bastide login

Sans installer, npx bastide login fait la même chose. D'autres façons d'installer, dont un binaire autonome qui n'exige pas Node, sont décrites avec leurs sommes SHA-256 sur https://bastide.app/installer.

Quand une version plus récente existe, la commande le signale une fois par jour sur la sortie d'erreur, dans un terminal seulement. Elle ne se met jamais à jour seule : npm install -g bastide le fait.

Note. Les anciens noms gs et glowsoft fonctionnent encore pendant une version, avec un avertissement. Vos scripts doivent passer à bastide.

Se connecter

bastide login utilise l'autorisation par appareil (RFC 8628) : aucun mot de passe ne passe par le terminal.

1. La commande affiche une adresse et un code de huit lettres, et ouvre votre navigateur s'il le peut. Avec --sans-navigateur, elle se contente d'afficher l'adresse.
2. L'écran Autoriser la ligne de commande de la console (https://console.bastide.app/appareil) montre le code. Vérifiez qu'il est bien celui de votre terminal ; sinon, refusez. Connectez-vous d'abord si besoin, second facteur compris.
3. Choisissez Autoriser. Le terminal reçoit un jeton personnel valable 90 jours, qui porte votre rang et toutes les portées. Le code expire au bout de dix minutes.
4. La commande range le jeton et lit vos organisations.

Où va le jeton : au trousseau du système (security sur macOS, secret-tool sur Linux, le coffre d'identifiants sur Windows). Sur un poste sans trousseau, il va dans un fichier identifiants.json lisible du seul propriétaire, et login le dit. Le jeton est rangé par adresse d'API.

Le jeton de login apparaît dans Compte, section « Vos jetons », sous le nom « Ligne de commande bastide (date) ».

Lier un dossier et déployer

bastide link --project-id prj_01JQ8ZK4M7NP2RSTVWXYZ34567
bastide deploy

link écrit .glowsoft/project.json dans le dossier courant, avec l'identifiant du projet et de l'organisation. Toute commande lancée dans ce dossier ou en dessous y prend le projet qu'on ne lui nomme pas. --repertoire <chemin> part d'un autre dossier.

deploy lance deployment.create sur l'environnement de production (ou --environment-id), à la référence --ref ou à la branche de l'environnement, puis suit l'état et le journal de construction jusqu'à un état final, et affiche l'adresse servie. --sans-suivi rend la main dès la création. Ctrl-C coupe le suivi, jamais le déploiement : il continue sur la plateforme. Le suivi s'arrête de lui-même au bout de trente minutes.

bastide logs lit les journaux d'exécution de l'environnement ; avec --suivre, il continue d'afficher les lignes qui arrivent. --since et --query bornent la lecture.

bastide doctor compare le dossier local à l'environnement déployé : version du moteur, gestionnaire de paquets, cadriciel, commandes d'installation, de construction et de démarrage, variables présentes d'un seul côté, commit servi, redirections et réécritures. Il dit, pour chaque écart, la commande qui rapproche les deux côtés, et sort avec le code 11 s'il en trouve un. Il compare les noms des variables, jamais leurs valeurs.

Les commandes engendrées

Toute opération du registre est une commande, sans une ligne écrite pour elle. Le chemin vient du nom de l'opération : bastide <ressource> <action>, avec autant de mots que de segments.

• Les options sont les champs de l'entrée, écrits en tirets : projectId devient --project-id.
• Une liste se donne en répétant l'option, ou d'un coup en JSON : --scopes project:read --scopes deploy:write, ou --scopes '["project:read","deploy:write"]'. Un objet se donne en JSON.
• bastide aide liste toutes les commandes ; bastide aide <commande> ou --aide en décrit les options.
• Les opérations d'écriture acceptent --idempotency-key : voir l'API.

La liste complète, option par option, est dans la référence de la ligne de commande.

Sorties et scripts

Aucune commande n'ouvre d'invite : rien n'attend une réponse au clavier. Seul login ouvre le navigateur.

• Sans option, la sortie est faite pour être lue par une personne et peut changer de mise en page d'une version à l'autre. Un contenu rapporté par un tiers (un nom de projet, un message de commit) y est suivi de « (rapporté) ».
• Avec --json, la sortie est le corps de la réponse tel que l'API le publie, sur une ligne. Son schéma est celui du document OpenAPI : c'est un contrat stable. Une erreur s'écrit alors sur la sortie d'erreur, sous la forme {"erreur": {"code", "cause", "suite", "message", "statut", "sortie"}}.
• deploy --json et logs --json écrivent une ligne JSON par événement : {"evenement":"cree",…}, {"evenement":"ligne","texte":…}, {"evenement":"etat",…}, {"evenement":"fin","deploymentId",…,"url"}.

Chaque erreur dit sa cause et la suite à donner, le plus souvent la commande à lancer ensuite.

Confirmer une opération

Une opération de classe E ou I (voir la réversibilité) demande --yes. Sans lui, la commande ne l'envoie pas et sort avec le code 12. Une opération irréversible se confirme en plus en deux temps : le premier envoi rend le refus confirmation_requise avec un nonce ; relancez la même commande avec --confirmation-nonce <nonce> dans les cinq minutes.

Codes de sortie

Les codes suivent la famille de la cause, pas le statut HTTP. Un numéro ne change jamais de sens. bastide aide sorties les liste.

Un script reprend sur 9 et 10, et abandonne sur 2 à 7.

Variables d'environnement

Un exemple d'intégration continue est dans Comptes de service et jetons.

Erreurs fréquentes

Voir aussi

• L'API HTTP
• Comptes de service et jetons
• Déployer
• La référence de la ligne de commande

Signaler une erreur sur cette page