# podman

A Dart client for the Podman **libpod API** over the Podman socket.

This package uses HTTP over Unix sockets and targets libpod endpoints directly,
without shelling out to the `podman` CLI.

## Features

- Typed `PodmanClient` API for system, container, and image operations
- Network lifecycle and connect/disconnect APIs
- Network exists/update/prune APIs
- Volume lifecycle APIs
- Pod lifecycle APIs
- Pod exists/admin/top/stats/prune APIs
- Container runtime helpers (`wait`, `healthStatus`, `exec`, `stats`)
- Container admin APIs (kill/pause/unpause/top/init/rename/update/mount/archive)
- Container checkpoint/restore APIs (including archive export/import helpers)
- System maintenance APIs (`system/df`, `system/check`, `system/prune`)
- Typed events API with reconnecting watch stream
- Unix-socket transport (`UnixSocketPodmanTransport`)
- Libpod API-first implementation (no Docker-compat fallback path)
- Focused option and model types
- Testable transport abstraction for deterministic unit tests

## Installation

```bash
dart pub add podman
```

## Quick Start

```dart
import 'package:podman/podman.dart';

Future<void> main() async {
  final client = PodmanClient();
  final version = await client.version();
  print('Podman server: ${version.serverVersion}');
  await client.close();
}
```

## Socket Resolution

By default, the transport resolves socket path in this order:

1. `PODMAN_SOCKET`
2. `$XDG_RUNTIME_DIR/podman/podman.sock`
3. `/run/user/$UID/podman/podman.sock`
4. `/run/podman/podman.sock`

You can override via:

```dart
final client = PodmanClient(socketPath: '/custom/path/podman.sock');
```

## Examples

- `example/version_info_example.dart`
- `example/list_containers_example.dart`
- `example/pull_and_run_example.dart`
- `example/inspect_container_example.dart`
- `example/secrets_workflow_example.dart`
- `example/manifest_workflow_example.dart`
- `example/artifact_workflow_example.dart`
- `example/generate_assets_example.dart`
- `example/play_kube_file_example.dart`
- `example/system_maintenance_example.dart`
- `example/checkpoint_restore_example.dart`

Copy/paste command guide:

- `doc/examples.md`

## Testing Backends

Default tests use a fake transport for deterministic unit coverage:

```bash
melos run test
```

Local integration tests can run against your local Podman socket:

```bash
melos run test:integration
```

Optional env vars:

- `PODMAN_TEST_SOCKET`: override socket path for local tests
- `PODMAN_LOCAL_TESTS=1`: alternate way to enable local tests