npm package: @idirdev/dockstat
Description: Docker container and image statistics
Author: idirdev
Latest version: 1.0.0

# dockstat

> **[EN]** A CLI tool to monitor Docker containers, images, volumes, and system disk usage from the terminal.
> **[FR]** Un outil CLI pour surveiller les conteneurs Docker, les images, les volumes et l'utilisation disque du système depuis le terminal.

---

## Features / Fonctionnalités

**[EN]**
- List running (or all) Docker containers with image and status
- Show real-time CPU and memory stats for running containers
- List Docker images with size information
- List Docker volumes with driver details
- Display Docker system disk usage summary
- Exits with error if Docker daemon is not running
- Lightweight wrapper with no extra dependencies

**[FR]**
- Lister les conteneurs Docker en cours (ou tous) avec image et statut
- Afficher les stats CPU et mémoire en temps réel des conteneurs
- Lister les images Docker avec leur taille
- Lister les volumes Docker avec les détails du driver
- Afficher le résumé d'utilisation disque du système Docker
- Quitte avec une erreur si le daemon Docker n'est pas actif
- Wrapper léger sans dépendances supplémentaires

---

## Installation

```bash
npm install -g @idirdev/dockstat
```

---

## CLI Usage / Utilisation CLI

```bash
# List running containers (default)
# Lister les conteneurs en cours (défaut)
dockstat

# List all containers including stopped
# Lister tous les conteneurs y compris ceux arrêtés
dockstat --all

# Show CPU and memory stats
# Afficher les stats CPU et mémoire
dockstat --stats

# List Docker images
# Lister les images Docker
dockstat --images

# List volumes
# Lister les volumes
dockstat --volumes

# Show disk usage summary
# Afficher le résumé d'utilisation disque
dockstat --disk

# Show help / Afficher l'aide
dockstat --help
```

### Example Output / Exemple de sortie

```
$ dockstat
api-server (node:20-alpine) Up 3 days
postgres-db (postgres:15) Up 3 days
redis-cache (redis:7-alpine) Up 3 days

$ dockstat --stats
api-server: CPU=0.42% MEM=128MiB / 2GiB
postgres-db: CPU=0.18% MEM=256MiB / 2GiB
redis-cache: CPU=0.05% MEM=12MiB / 2GiB

$ dockstat --images
node:20-alpine (142MB)
postgres:15 (379MB)
redis:7-alpine (29.5MB)
```

---

## API (Programmatic) / API (Programmation)

**[EN]** Use dockstat as a library to integrate Docker monitoring into your scripts.
**[FR]** Utilisez dockstat comme bibliothèque pour intégrer la surveillance Docker dans vos scripts.

```javascript
const {
  isDockerRunning,
  listContainers,
  getStats,
  getImages,
  getVolumes,
  getDiskUsage,
} = require('@idirdev/dockstat');

// Check if Docker is available
// Vérifier si Docker est disponible
if (!isDockerRunning()) {
  console.error('Docker is not running');
  process.exit(1);
}

// List running containers
// Lister les conteneurs en cours
const containers = listContainers(false);
containers.forEach(c => {
  console.log(`${c.name} [${c.image}] ${c.status}`);
});
// { id: 'a1b2c3d4', name: 'api-server', image: 'node:20-alpine', status: 'Up 3 days', ports: '0.0.0.0:4000->4000/tcp' }

// Get CPU / memory stats
// Obtenir les stats CPU / mémoire
const stats = getStats();
stats.forEach(s => console.log(`${s.name}: ${s.cpu} cpu, ${s.mem}`));

// List images
// Lister les images
const images = getImages();
images.forEach(i => console.log(`${i.name} ${i.size}`));

// Get raw disk usage string (docker system df)
// Obtenir la chaîne brute d'utilisation disque
console.log(getDiskUsage());
```

### API Reference

| Function | Parameters | Returns |
|----------|-----------|---------|
| `isDockerRunning()` | — | `boolean` |
| `listContainers(all?)` | all: boolean | `Array<{id, name, image, status, ports}>` |
| `getStats()` | — | `Array<{name, cpu, mem, net, block}>` |
| `getImages()` | — | `Array<{name, size, id}>` |
| `getVolumes()` | — | `Array<{name, driver}>` |
| `getDiskUsage()` | — | `string` |

---

## License

MIT - idirdev