> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coreweave.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Gérer les sandboxes avec la CLI

> Installez la CLI Sandboxes pour inspecter les sandboxes, exécuter des commandes, transférer des fichiers et gérer les instantanés.

L’interface en ligne de commande (CLI) `cwsandbox` permet de gérer vos sandboxes CoreWeave existantes depuis votre terminal. Elle vous permet d’inspecter les sandboxes, d’exécuter des commandes, de récupérer les journaux, de transférer des fichiers, de gérer les instantanés du système de fichiers et de nettoyer les ressources. La CLI s’installe en tant que composant facultatif du [client Python Sandboxes](https://docs.coreweave.com/fr/products/sandboxes/client.md).

Avant d’utiliser la CLI, créez vos sandboxes avec le SDK. Pour ce faire, suivez le [démarrage rapide sans serveur](https://docs.coreweave.com/fr/products/sandboxes/get-started.md) ou le guide [Utiliser votre propre infrastructure de calcul](https://docs.coreweave.com/fr/products/sandboxes/get-started-cks.md).

## Prérequis

Avant de commencer, préparez les éléments suivants :

* Un [environnement virtuel Python 3.11 ou version ultérieure actif](https://docs.coreweave.com/fr/products/sandboxes/client.md#prepare-your-python-environment) dans lequel `uv` est installé.
* Un identifiant d’authentification pour le compte propriétaire de vos bacs à sable. Consultez [Choisir et obtenir des identifiants](https://docs.coreweave.com/fr/products/sandboxes/placement.md#choose-and-get-credentials) pour savoir comment configurer les identifiants d’authentification et connaître les rôles requis.
* Une sandbox en cours d’exécution, pour exécuter des commandes, ouvrir des shells interactifs, récupérer les journaux, effectuer des opérations sur les fichiers et créer des instantanés.

## Installer et s’authentifier

Choisissez l’identifiant d’authentification que vous avez utilisé pour créer vos bacs à sable. Exécutez les commandes de l’un des onglets dans votre environnement virtuel actif, en remplaçant la valeur de substitution par votre clé ou votre jeton :

**Clé API Forge**

Installez les extras `cli` et `wandb`, puis sélectionnez la stratégie d’authentification W\&B pour votre clé API Forge :

```bash theme={"system"}
uv pip install --upgrade 'cwsandbox[cli,wandb]'
export WANDB_API_KEY="WANDB_API_KEY_VALUE"
export CWSANDBOX_AUTH="wandb"
cwsandbox --help
```

**Jeton d’accès à l’API CoreWeave**

Installez l’extra `cli` et sélectionnez l’authentification CoreWeave :

```bash theme={"system"}
uv pip install --upgrade 'cwsandbox[cli]'
export CWSANDBOX_API_KEY="API_ACCESS_TOKEN"
export CWSANDBOX_AUTH="coreweave_api_key"
cwsandbox --help
```

L’aide affiche la liste des commandes disponibles. Laissez les variables d’authentification définies dans le terminal où vous exécuterez les exemples suivants.

`CWSANDBOX_AUTH` détermine la stratégie d’authentification utilisée. L’option de premier niveau `--auth` la remplace le temps d’un seul appel. Par exemple, une fois les dépendances et les identifiants d’authentification Forge configurés :

```bash theme={"system"}
cwsandbox --auth wandb ls
```

Pour afficher les options d’une commande ou d’une sous-commande, utilisez `--help` :

```bash theme={"system"}
cwsandbox exec --help
cwsandbox files read --help
cwsandbox snapshots create --help
```

## Trouver vos bacs à sable

Listez les bacs à sable accessibles avec votre identifiant d’authentification :

```bash theme={"system"}
cwsandbox ls
```

Filtrez par statut, ou combinez un statut et une étiquette. Remplacez `TAG` par une étiquette associée à vos bacs à sable :

```bash theme={"system"}
cwsandbox ls --status running
cwsandbox ls --status running --tag "TAG" --output json
```

Le tableau par défaut affiche les ID des sandboxes, leurs statuts, leurs exécuteurs et leurs heures de démarrage. `--output json` renvoie une sortie structurée. Répétez `--tag` ou `--runner-id` pour indiquer plusieurs valeurs de filtre.

## Inspecter une sandbox

Remplacez `SANDBOX_ID_VALUE` par un ID renvoyé par `cwsandbox ls`, puis définissez-le dans votre terminal :

```bash theme={"system"}
export SANDBOX_ID="SANDBOX_ID_VALUE"
cwsandbox get "$SANDBOX_ID"
cwsandbox get "$SANDBOX_ID" --output json
```

Les exemples suivants utilisent cette variable. Les détails comprennent le statut de la sandbox, des informations sur l’exécuteur, l’heure de démarrage et, le cas échéant, le code de retour.

## Exécuter des commandes

Exécutez une commande dans une sandbox en cours d’exécution. La commande doit être disponible dans l’image de la sandbox :

```bash theme={"system"}
cwsandbox exec "$SANDBOX_ID" echo hello
cwsandbox exec "$SANDBOX_ID" python -c "print('hello')"
```

Pour définir le répertoire de travail distant, ajoutez l’option `--cwd` avant la commande distante. Remplacez `REMOTE_DIRECTORY` par un répertoire existant dans la sandbox :

```bash theme={"system"}
cwsandbox exec "$SANDBOX_ID" --cwd "REMOTE_DIRECTORY" pwd
```

La CLI transmet en continu la sortie standard et la sortie d’erreur standard à votre terminal local. Lorsque la commande distante se termine normalement, la CLI s’arrête en renvoyant le même code de sortie.

## Ouvrir un shell interactif

Depuis un terminal local sous macOS ou Linux, ouvrez un shell interactif :

```bash theme={"system"}
cwsandbox sh "$SANDBOX_ID"
```

Le shell par défaut est `/bin/bash`. Utilisez `--cmd` pour choisir un autre shell ou un programme interactif installé dans le sandbox :

```bash theme={"system"}
cwsandbox sh "$SANDBOX_ID" --cmd /bin/sh
cwsandbox sh "$SANDBOX_ID" --cmd "python -i"
```

Le shell interactif nécessite un terminal à la fois pour l’entrée standard et pour la sortie standard, et n’est pas pris en charge sous Windows. Pour quitter une session shell, saisissez `exit` ou appuyez sur `Ctrl+D`. `Ctrl+C` est transmis au processus distant.

## Afficher les journaux

Récupérez les journaux du processus principal de la sandbox :

```bash theme={"system"}
cwsandbox logs "$SANDBOX_ID" --tail 100
cwsandbox logs "$SANDBOX_ID" --tail 100 --timestamps
```

Utilisez `--follow` pour afficher en flux continu la nouvelle sortie des journaux. Appuyez sur `Ctrl+C` pour arrêter le suivi :

```bash theme={"system"}
cwsandbox logs "$SANDBOX_ID" --follow
```

Utilisez `--since` pour filtrer les journaux à partir d’un horodatage. Remplacez `2026-09-10 09:00:00` par l’heure de début souhaitée. La CLI interprète un horodatage sans fuseau horaire comme étant exprimé en UTC :

```bash theme={"system"}
cwsandbox logs "$SANDBOX_ID" --since "2026-09-10 09:00:00"
```

Les journaux contiennent la sortie standard et la sortie d’erreur standard du processus principal, c’est-à-dire la commande utilisée pour créer le sandbox. Ils n'incluent pas la sortie de `cwsandbox exec`. Les bacs à sable créés avec la commande keep-alive par défaut ne produisent aucune sortie dans les journaux.

Pour récupérer les journaux, le sandbox doit être en cours d’exécution. Récupérez donc les journaux avant d’arrêter le sandbox. Pour plus d'informations, voir [Journalisation des sandboxes](https://docs.coreweave.com/fr/products/sandboxes/client/guides/logging.md).

## Lire et écrire des fichiers

Les opérations sur les fichiers nécessitent une sandbox en cours d’exécution. Pour afficher un fichier distant sur la sortie standard, remplacez `REMOTE_PATH` par son chemin dans la sandbox :

```bash theme={"system"}
cwsandbox files read "$SANDBOX_ID" "REMOTE_PATH"
```

Pour télécharger le fichier, ajoutez `--output` suivi d’une destination locale. Remplacez `LOCAL_PATH` par le chemin où vous souhaitez l’enregistrer :

```bash theme={"system"}
cwsandbox files read "$SANDBOX_ID" "REMOTE_PATH" --output "LOCAL_PATH"
```

Pour téléverser un fichier, indiquez d’abord la destination distante, puis le fichier source local existant :

```bash theme={"system"}
cwsandbox files write "$SANDBOX_ID" "REMOTE_PATH" "LOCAL_PATH"
```

## Gérer les instantanés du système de fichiers

La création d'un instantané nécessite une sandbox en cours d'exécution configurée avec un [point de montage d'instantané du système de fichiers](https://docs.coreweave.com/fr/products/sandboxes/file-system-snapshots.md#start-a-sandbox-with-a-snapshot-mount). Les instantanés du système de fichiers doivent être activés pour votre organisation.

Pour créer un instantané :

```bash theme={"system"}
cwsandbox snapshots create "$SANDBOX_ID"
```

La commande attend que l’instantané soit prêt, puis affiche son ID. Pour rendre la main sans attendre qu’il soit prêt et afficher l’ID au format JSON, utilisez :

```bash theme={"system"}
cwsandbox snapshots create "$SANDBOX_ID" --no-wait --output json
```

Listez les instantanés ou filtrez-les pour n’afficher que les instantanés prêts créés à partir d’une sandbox donnée :

```bash theme={"system"}
cwsandbox snapshots list
cwsandbox snapshots list --source-sandbox-id "$SANDBOX_ID" --status ready
```

Pour inspecter un instantané, remplacez `SNAPSHOT_ID_VALUE` par son identifiant :

```bash theme={"system"}
export SNAPSHOT_ID="SNAPSHOT_ID_VALUE"
cwsandbox snapshots get "$SNAPSHOT_ID"
cwsandbox snapshots get "$SNAPSHOT_ID" --output json
```

Pour supprimer un instantané dont vous n’avez plus besoin, exécutez :

```bash theme={"system"}
cwsandbox snapshots delete "$SNAPSHOT_ID"
```

Pour connaître les exigences relatives aux instantanés, les types de stockage pris en charge et la procédure de restauration d’une sandbox avec le SDK, consultez [Instantanés du système de fichiers](https://docs.coreweave.com/fr/products/sandboxes/file-system-snapshots.md).

## Arrêter ou supprimer une sandbox

Arrêtez une sandbox lorsque vous avez fini de l’utiliser :

```bash theme={"system"}
cwsandbox stop "$SANDBOX_ID"
```

Pour laisser jusqu’à 30 secondes à un arrêt en douceur, utilisez plutôt la variante suivante :

```bash theme={"system"}
cwsandbox stop "$SANDBOX_ID" --graceful-shutdown-seconds 30
```

Pour une sandbox configurée avec un montage d’instantané du système de fichiers, utilisez plutôt la méthode suivante pour capturer un instantané avant de l’arrêter :

```bash theme={"system"}
cwsandbox stop "$SANDBOX_ID" --snapshot-on-stop
```

Pour supprimer une sandbox, exécutez :

```bash theme={"system"}
cwsandbox delete "$SANDBOX_ID"
```

Pour les scripts de nettoyage, utilisez `--missing-ok` afin qu'une sandbox déjà inexistante ne provoque pas d'erreur :

```bash theme={"system"}
cwsandbox delete "$SANDBOX_ID" --missing-ok
```