docker-shelf

README

shelf 📦

A filesystem-like organizer for Docker containers.

Organize your containers into hierarchical "shelves" and navigate them like directories. Perfect for developers managing multiple projects with dozens of containers.

📦 SHELF
└── project
    └── backend
        └── 🟢 my-api (running)
    └── frontend  
        └── 🟢 my-nginx (running)
└── databases
    └── 🟢 postgres-prod (running)
    └── 🔴 postgres-dev (exited)

Features

• Hierarchical organization - Organize containers like a filesystem
• Navigation - cd into shelves, list contents with ls
• Tree view - Visualize your entire container organization
• Flexible tagging - Use Docker labels or local assignments
• Persistent context - Remembers your current location

Installation

Via Homebrew (macOS/Linux)

brew tap alessandropitocchi/shelf
brew install shelf

Via Go

go install github.com/alessandropitocchi/docker-shelf@latest

Build from source

git clone https://github.com/alessandropitocchi/docker-shelf.git
cd docker-shelf
make build
make install

Quick Start

# Create shelves
shelf make project/backend
shelf make project/frontend

# Organize containers
shelf shelve my-api project/backend
shelf shelve my-nginx project/frontend

# Navigate and view
shelf tree                    # see the full map
shelf cd project/backend      # focus on backend
shelf ls                      # list containers here

Usage

shelf <command> [args]

If you run shelf with no arguments, it prints the full tree.

Navigation Commands

Command	Description
cd [path]	Switch current shelf (interactive if no path)
pwd	Print current shelf path
ls [path]	List containers in current or specified shelf
tree	Show full warehouse map

Organization Commands

Command	Description
shelve <container> <path>	Assign a container to a shelf
remove <container>	Remove a container from custom shelf
make <path>	Create an empty shelf
burn <path>	Delete an empty shelf

Other Commands

Command	Description
help	Show help menu
version	Show version information

How Shelf Paths Are Resolved

When building the tree or listing containers, shelf uses this priority order:

1. Custom assignment created with shelve (stored in ~/.config/shelf/storage.json)
2. Docker label io.shelf.path (if present on the container)
3. Falls back to Orphans

Using Docker Labels

You can set the shelf path when creating containers:

docker run -d \
  --label io.shelf.path=/project/backend \
  --name my-api \
  my-api-image

Or in docker-compose.yml:

services:
  api:
    image: my-api-image
    labels:
      - "io.shelf.path=/project/backend"

Examples

# Create a shelf structure
shelf make project/database
shelf make project/backend
shelf make project/frontend

# Assign containers to shelves
shelf shelve postgres project/database
shelf shelve redis project/database
shelf shelve api-server project/backend
shelf shelve nginx project/frontend

# Navigate to a shelf
shelf cd project/backend

# List containers in current shelf
shelf ls

# View a specific shelf without changing context
shelf ls project/database

# See the whole structure
shelf tree

# Remove a container from its shelf
shelf remove postgres

# Delete an empty shelf
shelf burn project/old-stuff

Data Files

Shelf stores its configuration under ~/.config/shelf/:

• storage.json - Container assignments and shelf definitions
• state.json - Current shelf path (context)

Requirements

• Docker Engine running and accessible from your shell
• Go 1.21+ (for building from source)

Development

# Build
make build

# Install locally
make install

# Run tests
make test

# Format code
make fmt

# See all available commands
make help

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE file for details.

Troubleshooting

Container listing fails:

• Confirm Docker is running: docker ps
• Check Docker socket permissions

Container doesn't appear under expected shelf:

• Check if it has a custom assignment: shelf ls /
• Verify Docker label: docker inspect <container> | grep io.shelf.path

Context seems wrong:

• Check current context: shelf pwd
• Reset to root: shelf cd /