dockit-tool 0.1.2
A production-grade Docker wrapper CLI focused on usability and simplicity
License: MIT
Requires Python: >=3.9

# dockit

[![Tests](https://github.com/developerdevice/Dockit/actions/workflows/tests.yml/badge.svg)](https://github.com/developerdevice/Dockit/actions)
[![Code Quality](https://github.com/developerdevice/Dockit/actions/workflows/quality.yml/badge.svg)](https://github.com/developerdevice/Dockit/actions)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)

A lightweight Docker wrapper CLI that eliminates tedious container ID lookups and verbose command repetition.

## What This Is

dockit is a practical CLI wrapper for Docker and Docker Compose. It reduces friction in everyday workflows by:

- Working with container names instead of IDs
- Providing sensible defaults (no flags = do the right thing)
- Auto-detecting Docker engine and Compose version
- Formatting output clearly and without truncation
- Supporting all major shells with completion

## What This Is Not

This project is intentionally **not**:

- A container engine (it wraps Docker)
- A Docker replacement (it enhances the existing CLI)
- A Kubernetes tool
- A UI or dashboard
- A configuration management system
- A DevOps platform

If you need Docker's full capabilities, use Docker directly. If you want to reduce boilerplate in local development and debugging, dockit is for you.

## Design Philosophy

**Simplicity over features** — Only implement what most users need daily.

**Predictability** — Commands map obviously to their Docker equivalents. No magic. No hidden behavior.

**Zero breaking changes** — Once you learn dockit, it stays consistent.

**Scriptable** — Output is clean, parseable, and exit codes are meaningful.

**Human-first** — Optimize for typing, reading, and understanding—not for machines.

## Installation

For detailed installation instructions, see [INSTALL.md](INSTALL.md).

### Quick Install

```bash
pip install dockit
dockit version
```

Available globally after installation.

## Quick Start

### List containers

```bash
# Running containers
dockit ps

# All containers (including stopped)
dockit ps --all
```

### View logs

```bash
# Stream logs
dockit logs myapp -f

# Logs from the last 10 minutes
dockit logs myapp --since 10m

# Filter by pattern
dockit logs myapp --grep "ERROR"
```

### Open a shell

```bash
dockit shell myapp
# Falls back to /bin/sh if bash is unavailable
```

### Manage containers

```bash
dockit restart myapp
dockit start myapp
dockit stop myapp
dockit rm myapp -f  # Force remove
```

### Manage stacks

```bash
# Start compose stack (detached)
dockit up

# Stop and remove
dockit down

# Restart services
dockit restart

# Remove volumes too
dockit down -v
```

### Cleanup

```bash
# Remove unused images, containers, volumes, networks
dockit clean

# Include all unused resources
dockit clean --all

# Preview what would be deleted
dockit clean --dry-run
```

### Shell completion

```bash
# Install completion for your shell
dockit --install-completion

# Restart your shell
exec $SHELL
```

Available for bash, zsh, fish, and PowerShell.

## How It Works

dockit detects your Docker setup automatically:

- **Docker engine** — Looks for `docker`, falls back to `podman`
- **Compose version** — Checks for `docker compose` (v2), falls back to `docker-compose` (v1)
- **Compose file** — Searches for `compose.yaml` or `docker-compose.yml`

All detection happens once per command. No polling, no daemons, no background processes.

## Documentation

Full command reference, engine detection details, and extension guidelines are in [docs/wiki.md](docs/wiki.md).

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for:

- CI/CD pipeline details
- How to run tests locally
- Code quality checks
- Pull request process

### Report a bug

Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.yml). Include:

- OS and version
- Docker version
- Full command output
- Steps to reproduce

### Propose a feature

Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.yml). Proposals must:

- Be based on real workflows, not hypotheticals
- Show the current Docker command you're using
- Explain why the proposed wrapper improves it

### Contribute code

1. Fork the repository
2. Create a feature branch
3. Write tests for your changes
4. Ensure all tests pass: `pytest`
5. Submit a pull request

**Coding standards:**

- Follow Python idioms; prefer clarity over cleverness
- No over-engineering or unnecessary abstraction
- Test coverage should not decrease
- Commit messages should be clear and specific
- Keep the codebase maintainable by future contributors

## License

MIT