Box CLI

Utilise Box CLI installé pour accomplir et vérifier les opérations Box.

Flux de travail opérationnel

Identifie le résultat demandé, la cible et l'acteur. Si la demande laisse une cible à risque, un destinataire, un rôle, un utilisateur usurpé ou une portée de lot ambigus, pose une seule question ciblée avant d'exécuter une commande.
Confirme l'environnement CLI et l'utilisateur actif avant l'opération. Si l'utilisateur nomme un environnement, inspecte box configure:environments:select --help et sélectionne cet environnement avant de vérifier l'identité :
```
box users:get me --json --fields id,name,login
```
Inclus --as-user <USER_ID> dans la vérification d'identité quand l'usurpation est autorisée. users:get me confirme l'utilisateur actif, non le nom d'environnement. Réutilise les mêmes commandes de contrôle d'environnement et d'acteur tout au long de l'opération et de sa vérification ; répète la vérification après tout changement d'environnement ou d'acteur autorisé. Ne bascule jamais vers une identité plus privilégiée simplement pour contourner une erreur.
Résout les noms lisibles en identifiants Box stables avant mutation. Si plusieurs éléments correspondent, présente les candidats et demande à l'utilisateur de choisir.
Préfère une commande CLI dédiée. Ajoute --json pour une sortie lisible par machine et limite --fields aux données nécessaires pour la tâche.
Vérifie les mutations avec une lecture en utilisant le même acteur. Pour les suppressions, vérifie la collection parent ou la corbeille selon le cas ; un 404 seul peut aussi signifier que l'acteur n'a pas accès. Pour les opérations asynchrones, rapporte le statut en attente jusqu'à confirmation d'achèvement.
Rapporte l'acteur, l'action, les identifiants d'objet pertinents, la preuve de vérification et tout échec non résolu. Inclus les commandes quand elles aident l'utilisateur à reproduire le résultat.

Motifs courants

Enregistre box --version. Inspecte l'aide des commandes quand la syntaxe est inconnue, la version installée diffère de la version vérifiée ci-dessous, ou une commande est rejetée. Résous l'incertitude avant d'exécuter une écriture.

# Identifier l'acteur
box users:get me --json --fields id,name,login

# Inspecter le dossier racine et un ensemble délimité d'enfants
box folders:get 0 --json --fields id,name
box folders:items 0 --json --fields id,type,name --max-items 20

# Chercher et préserver les informations parent pour désambiguïsation
box search "Launch Plan" --json --fields id,type,name,parent --limit 20

# Lire un élément par ID
box files:get <FILE_ID> --json --fields id,name,parent,owned_by
box folders:get <FOLDER_ID> --json --fields id,name,parent,owned_by

# Créer, puis vérifier l'ID de dossier retourné
box folders:create <PARENT_FOLDER_ID> "Approved Assets" --json
box folders:get <RETURNED_FOLDER_ID> --json --fields id,name,parent

Box utilise 0 comme identifiant de dossier racine. Un chemin ou un nom d'élément n'est pas un identifiant stable.

Utilise box <topic>:<command> --help pour vérifier les drapeaux et l'ordre des arguments dans la version installée.

Configuration et authentification

Entre en mode configuration uniquement quand le CLI est absent, l'authentification échoue, ou l'utilisateur le demande.

npm install --global @box/cli
box login -d

box login -d utilise l'application officielle Box CLI pour les opérations de contenu interactif.
Dans un environnement sans affichage, demande à l'utilisateur d'exécuter box login -d --code dans son propre terminal pour l'application officielle CLI, ou box login --platform-app --code pour son application personnalisée. --code est un drapeau booléen : le CLI affiche une URL d'autorisation, puis demande l'état et le code d'autorisation après que l'utilisateur autorise dans un navigateur externe. Entre ces valeurs uniquement aux invites CLI locales.
Utilise box login --platform-app quand l'utilisateur a besoin d'une application OAuth personnalisée ou de portées au-delà de l'application officielle CLI.
Pour l'automatisation serveur approuvée avec JWT ou Client Credentials Grant, utilise le flux courant box configure:environments:add --help et protège le fichier de configuration en dehors du contrôle source.
Les jetons développeur sont pour des tests locaux courts. N'incorpore pas de jetons, de secrets client, de clés privées ou de codes d'autorisation dans les commandes, les invites, les journaux, les fixtures ou les fichiers de repository.

Après la configuration, vérifie l'identité avec box users:get me ; n'affiche pas les magasins d'identifiants ou la configuration d'environnement brute.

Travail risqué et destructeur

La demande doit explicitement autoriser la portée exacte avant :

supprimer ou supprimer définitivement du contenu ;
créer, modifier ou supprimer des collaborations ou des liens partagés ;
usurper l'identité d'un autre utilisateur ;
modifier les utilisateurs, groupes, rétention ou paramètres de gouvernance de l'entreprise ; ou
exécuter un lot large qui peut modifier de nombreux objets.

Si cette autorisation est absente, affiche l'acteur, les identifiants cible, le rôle ou le changement proposé et la taille du lot, puis demande une confirmation. Ne t'appuie pas sur les invites CLI car certaines commandes destructrices ne demandent pas confirmation.

Exécute les écritures dépendantes en série. Sérialise les processus partageant un environnement OAuth pour éviter les rafraîchissements de jetons ou changements d'environnement chevauchants. Vérifie en utilisant les identifiants retournés.

Opérations en masse et récupération

Utilise l'entrée CSV ou JSON via --bulk-file-path uniquement quand la commande spécifique supporte ce drapeau. Vérifie l'aide de la commande et les exemples en masse officiels pour les colonnes et valeurs imbriquées supportées. Avant d'exécuter un lot :

Valide les colonnes d'entrée par rapport aux arguments et drapeaux de la commande. Les valeurs de ligne substituent les valeurs de ligne de commande, y compris as-user ; inspecte les substitutions d'acteur et de cible avant l'exécution.
Valide un petit sous-ensemble représentatif quand l'opération est réversible et l'utilisateur l'a autorisée.
Conserve un enregistrement de rapprochement séparé de l'entrée CLI, avec le numéro ou la clé de la ligne source, l'identifiant cible voulu, l'acteur et le résultat. N'ajoute pas de colonnes de suivi que la commande ne supporte pas.
Capture la sortie et les diagnostics d'erreur par ligne. L'exécution en masse peut continuer après les défaillances de ligne et terminer sans un statut de sortie non nul ; réconcilie chaque ligne avant de rapporter le succès.

Pour les défaillances partielles :

Traite les lignes réussies comme validées jusqu'à ce que la vérification prouve le contraire.
Recommence les réponses 429 uniquement après le délai indiqué.
Recommence les timeouts ou réponses 5xx uniquement quand l'opération est idempotente ou une lecture prouve que la mutation n'a pas eu lieu.
Ne recommence pas les écritures 401, 403 ou ambigües inchangées. Corrige d'abord l'identité, la permission ou l'état.
Recommence uniquement le sous-ensemble échoué vérifié-sûr, puis réconcilie chaque ligne source par rapport à Box.

Ne recommence jamais un lot de mutations partiellement réussi entier simplement parce que certaines lignes ont échoué.

Fallback REST

Quand aucune commande dédiée n'existe, préfère box request car elle réutilise l'identité CLI sélectionnée :

box request /folders/0/items --query "limit=5" --json

Inspecte box request --help avant une écriture. Utilise des valeurs explicites de méthode, corps et requête, puis vérifie l'objet Box résultant par une lecture. curl brut avec un bearer token est en dehors du flux de travail normal et doit être utilisé uniquement quand l'utilisateur fournit un mécanisme d'authentification sécurisé approuvé.

Sources publiques actuelles

Utilise ces sources quand l'aide installée est insuffisante :

Exemples et drapeaux d'authentification vérifiés le 2026-10-13 par rapport à la source et la documentation publiques Box CLI au commit 97e4351cb5e4a2077f37090bb5aca0ae2fe7020f (version de package 4.10.1).

box-cli