RankApp CLI

Personnalisez le thème de votre site RankApp depuis votre éditeur ou avec votre assistant IA. Récupérez le thème et les données de votre catalogue, modifiez les fichiers en local, puis envoyez votre travail avec Git pour le vérifier dans un aperçu RankApp.

La CLI donne accès à un site précis, pour une durée limitée, avec les droits accordés par son propriétaire. L'envoi du thème met à jour le brouillon ; la mise en ligne fait l'objet d'une commande distincte.

Premiers pas · Modifier le thème · Pages et menus · Commandes · Dépannage · Accès et sécurité

Avant de commencer

• Un site RankApp et un jeton d'accès à ce site, généré dans RankApp.
• Git et uv installés.
• Python 3.12 ou plus récent pour exécuter la CLI.
• Un trousseau de mots de passe accessible à la session : Trousseau sur macOS, gestionnaire d'identifiants sur Windows, ou un service compatible avec keyring sur Linux.

Un compte PyPI n'est pas nécessaire pour installer ou utiliser RankApp CLI. Le jeton demandé par rankapp site login provient de RankApp, pas de PyPI.

Premiers pas

1. Installer la CLI

uv tool install --upgrade rankapp-cli
rankapp --version

L'installation fournit deux exécutables : rankapp et git-remote-rankapp. Le second permet à Git de communiquer avec votre site ; Git l'appelle pour vous.

Si le terminal ne trouve pas rankapp, exécutez uv tool update-shell, puis ouvrez un nouveau terminal. Les deux exécutables doivent être dans le PATH.

2. Connecter votre site

Dans la personnalisation de votre site dans RankApp, générez le prompt d'accès destiné à votre assistant. Il contient la commande de connexion, les droits accordés et la date d'expiration. Utilisez la commande fournie ou remplacez la valeur ci-dessous par votre jeton :

rankapp site login "VOTRE_JETON_RANKAPP"

La CLI valide l'accès auprès de RankApp et conserve le jeton dans le trousseau du système. Ne l'ajoutez pas aux fichiers de votre site.

3. Récupérer le thème et le catalogue

Placez-vous dans le dossier qui accueillera votre projet, puis lancez :

rankapp site pull

La commande crée un dossier portant le nom de votre site, avec le thème, un dépôt Git sur la branche main, le remote rankapp, un export du catalogue pour l'aperçu local et un fichier AGENTS.md.

Entrez dans le dossier créé — ma-boutique est un exemple — et ouvrez AGENTS.md dans votre éditeur avant toute modification :

cd ma-boutique
rankapp site check

AGENTS.md décrit les règles du site, la syntaxe des champs, les langues et les budgets. Un contrôle réussi renvoie un objet JSON avec "valid": true.

Pour choisir le dossier de destination, utilisez rankapp site pull mon-dossier. Ce dossier doit être absent ou vide.

4. Modifier et voir le résultat

Depuis le dossier du site :

rankapp site dev

Ouvrez http://127.0.0.1:4600. Modifiez le thème dans votre éditeur, puis actualisez la page : les fichiers sont relus à chaque requête. Aucun serveur Node.js n'est nécessaire.

Cette commande reste active. Gardez ce terminal ouvert et utilisez-en un second dans le même dossier pour les commandes suivantes, ou arrêtez le serveur avec Ctrl+C.

L'aperçu utilise les données récupérées lors du pull. Il permet de vérifier les pages et leur présentation ; les comptes clients, le panier et le paiement dépendent des services en ligne. Certains médias distants nécessitent également une connexion. L'aperçu RankApp permet de vérifier les interactions disponibles, comme la recherche et le panier ; le paiement y est désactivé.

5. Envoyer le brouillon et obtenir un aperçu

Après vos modifications, vérifiez le thème et relisez votre diff avant de créer un commit :

rankapp site check
git diff
git status --short
git add -A
git diff --cached
git commit -m "Personnaliser le thème de la boutique"
git push rankapp main
rankapp site preview

Le push envoie les fichiers de thème modifiés et les suppressions. RankApp valide et compile le brouillon. preview renvoie un lien temporaire et sa date d'expiration ; ouvrez ce lien complet pour vérifier le résultat ou le faire valider au propriétaire du site.

6. Publier après validation

Cette commande demande la mise en ligne du brouillon. Exécutez-la uniquement après validation explicite du propriétaire, avec un jeton autorisant site:publish et un abonnement Site autorisant la publication :

rankapp site publish

La réponse contient l'identifiant et l'état de la compilation. La CLI n'attend pas sa réussite : suivez son état dans RankApp, puis ouvrez le site public pour confirmer que la mise en ligne est terminée.

Action	Résultat
rankapp site check	Contrôle les fichiers locaux.
rankapp site dev	Affiche le thème local avec le catalogue récupéré.
git push rankapp main	Met à jour le brouillon sur RankApp.
rankapp site preview	Crée un lien temporaire vers l'aperçu du brouillon.
rankapp site publish	Lance la publication du brouillon, à suivre dans RankApp.

Modifier le thème

La structure exacte dépend du thème récupéré. Les dossiers reconnus sont :

ma-boutique/
├── AGENTS.md       Règles et syntaxe propres au site
├── assets/         CSS, JavaScript, SVG et images
├── blocks/         Blocs du thème
├── config/         Configuration et réglages du thème
├── layout/         Structure générale des pages
├── locales/        Textes traduits du thème
├── sections/       Sections réutilisables
├── snippets/       Fragments Liquid réutilisables
└── templates/      Modèles de pages, en Liquid ou JSON selon le thème

Déclarer un champ éditable

Dans un template Liquid, le tag field déclare un champ et affiche sa valeur :

<h1>{% field title | input, required %}</h1>
<p>{% field introduction | textarea %}</p>

Les contrôles disponibles sont input, textarea, richtext, image et post. Les modificateurs required et shared rendent respectivement un champ obligatoire ou commun aux langues. text n'est pas un contrôle valide.

Les pages proposées par le thème utilisent les déclarations Liquid page et field_default. Leur syntaxe, leurs contenus par défaut et les règles de traduction figurent dans AGENTS.md. Préservez les chemins de templates et les noms des champs pour conserver leur association aux contenus enregistrés.

Formats et budgets

Limite	Valeur
Nombre de fichiers de thème	2 000 maximum
Taille d'un fichier	1 Mio maximum, soit 1 048 576 octets
Taille totale du thème	25 Mio maximum, soit 26 214 400 octets
Fichiers texte	.liquid, .json, .css, .js, .svg, .txt
Images dans assets/	.avif, .gif, .jpeg, .jpg, .png, .webp

Les images comptent dans les budgets. Les liens symboliques sont refusés. check valide les fichiers, la syntaxe et les champs localement ; le serveur effectue aussi ses contrôles lors du push, notamment sur les références des pages. Consultez les pages existantes avant de supprimer ou renommer un modèle.

Pages et menus

Les fichiers du thème définissent la présentation. Les contenus des pages sont enregistrés dans RankApp et se consultent depuis le dossier du site :

rankapp site pages list
rankapp site pages get "IDENTIFIANT_DE_PAGE"

list renvoie les pages et les schémas des templates ; get permet de retrouver une page précise. Les sorties sont au format JSON.

Pour créer, modifier ou supprimer des pages personnalisées, utilisez l'application RankApp. Les commandes pages save et pages delete sont présentes dans l'aide, mais les jetons temporaires de site décrits dans ce guide ne sont actuellement pas autorisés à les utiliser par l'API.

Les pages proposées par le thème se déclarent dans les templates avec page et field_default ; consultez AGENTS.md pour ce parcours. Les menus se gèrent également dans l'application RankApp.

Commandes

Exécutez les commandes de travail depuis le dossier du site, sauf login, logout et le premier pull.

Commande	Usage
rankapp --version	Affiche les versions de la CLI et du moteur de rendu.
rankapp site login "JETON"	Valide et enregistre l'accès au site.
rankapp site logout	Retire l'accès du trousseau et la configuration locale active.
rankapp site pull [dossier]	Crée un nouveau dépôt local avec le thème et le catalogue.
rankapp site check	Vérifie le thème local.
rankapp site dev	Démarre l'aperçu sur le port 4600.
rankapp site preview	Crée un lien d'aperçu temporaire.
rankapp site publish	Lance la publication, si le droit a été accordé.
rankapp site pages list	Consulte les pages et les templates.
rankapp site pages get "ID"	Consulte une page par son identifiant.

L'aide est disponible à chaque niveau :

rankapp --help
rankapp site --help
rankapp site pages get --help

Dépannage

La commande rankapp ou git-remote-rankapp est introuvable

Exécutez uv tool update-shell, puis ouvrez un nouveau terminal. Vérifiez l'installation avec rankapp --version et uv tool list.

Le dossier existe déjà — WORKSPACE_NOT_EMPTY

rankapp site pull crée un nouveau dépôt ; il ne met pas à jour un dossier existant. Pour reprendre un thème déjà récupéré, entrez dans son dossier et utilisez Git.

Pour obtenir un catalogue local actualisé, récupérez le site dans un nouveau dossier. git pull rankapp main synchronise le thème, sans rafraîchir l'export du catalogue. Conservez vos modifications locales avant de changer de dossier.

Le push est refusé parce que le brouillon a changé

Committez d'abord vos modifications locales, puis récupérez le thème distant :

git pull --no-rebase rankapp main

Si Git signale des conflits, résolvez-les, vérifiez le résultat, puis terminez la fusion avec git add et git commit. Relancez ensuite :

rankapp site check
git push rankapp main

Le remote accepte uniquement main et refuse les pushes forcés.

Un fichier hors thème bloque le push — THEME_PATH_INVALID

En plus d'AGENTS.md et de .gitignore, seuls les fichiers des dossiers de thème sont acceptés dans le commit envoyé. Placez vos notes, exports et fichiers de travail locaux dans .rankapp/, déjà ignoré par Git, et vérifiez git diff --cached avant de committer.

Le jeton a expiré, a été révoqué ou n'a pas le droit nécessaire

Générez un nouvel accès dans RankApp et relancez rankapp site login. Une connexion à un autre site remplace le profil actif : reconnectez le bon site en cas de SITE_MISMATCH. Un accès autorisant le brouillon ou l'aperçu n'autorise pas nécessairement la publication.

Le trousseau n'est pas disponible — KEYRING_UNAVAILABLE

Déverrouillez le trousseau de votre session. Sur Linux, vérifiez qu'un service de secrets compatible est disponible. Un conteneur ou une session distante sans trousseau demande une configuration adaptée ; la CLI ne se rabat pas sur un stockage du jeton en clair.

Le port est occupé — DEV_PORT_IN_USE

Le port de l'aperçu est 4600. Réutilisez le serveur s'il correspond à votre projet, ou arrêtez l'instance que vous avez lancée avec Ctrl+C. Un autre port n'est pas pris en charge par cette version.

Le format du catalogue n'est pas reconnu — SNAPSHOT_VERSION_UNSUPPORTED

Mettez à jour la CLI avec uv tool install --upgrade rankapp-cli, puis récupérez le site dans un nouveau dossier. Pour remplacer une ancienne installation de développement locale, utilisez uv tool install --reinstall rankapp-cli.

Accès et sécurité

• Le jeton est limité à un site, aux droits accordés et à sa date d'expiration.
• Le jeton est conservé dans le trousseau ; ne le copiez ni dans un dépôt Git, ni dans un fichier partagé, ni dans une documentation publique.
• Le dépôt contient un export local du catalogue. Traitez ce dossier comme des données de votre site et ne le publiez pas dans un dépôt public.
• Aucun identifiant AWS n'est nécessaire. Les transferts de fichiers utilisent des autorisations temporaires fournies par RankApp.
• Un assistant IA doit respecter le périmètre donné par le propriétaire et demander sa validation avant rankapp site publish.
• logout supprime l'accès de cette machine. Il n'efface pas les fichiers récupérés et ne révoque pas le jeton côté RankApp.

Lorsque vous avez terminé :

rankapp site logout

Liens utiles

• RankApp
• Versions et fichiers du paquet sur PyPI
• Installer uv
• Configurer le trousseau système avec keyring

Licence : MIT.