@rotorsoft/contui

A terminal UI for managing containers on macOS using the native container CLI.

Features

• Container Management: List, start, stop, restart, and remove containers
• Image Management: List, pull, inspect, and remove images
• Network Management: List, create, inspect, and remove networks
• Volume Management: List, create, inspect, and remove volumes
• Vim-style Navigation: Use j/k or arrow keys for navigation
• Search/Filter: Quickly filter resources with /
• Real-time Refresh: Auto-refresh data with r key
• Detailed Inspection: View full resource details with Enter or i
• Container Logs: View container logs with L

Prerequisites

• macOS with native container support
• Node.js >= 18.0.0
• The container CLI must be installed and the container service running

Installation

Download and Run (npm)

# Install globally
npm install -g @rotorsoft/contui

# Run the CLI
contui

# Or run without installing
npx @rotorsoft/contui

From Source (pnpm)

# Clone the repository
git clone https://github.com/Rotorsoft/contui.git
cd contui

# Install dependencies
pnpm install

# Build the project
pnpm run build

# Run the application
pnpm start

Global Installation

# Link for global usage
pnpm link --global

# Run from anywhere
contui

Usage

Keyboard Shortcuts

Navigation

| Key | Action | |-----|--------| | 1-4 | Switch tabs (Containers, Images, Networks, Volumes) | | h / l | Previous/Next tab | | j / k or ↓ / ↑ | Navigate list | | Enter | Inspect selected item | | Esc | Go back / Cancel | | q | Quit |

Actions

| Key | Action | |-----|--------| | n | Run new container (Containers/Images tab) | | e | Edit container (recreate with new settings) | | s | Start container | | x | Stop container | | R | Restart container | | d | Delete (with confirmation) | | L | View container logs | | i | Inspect details | | p | Pull image (Images tab) | | c | Create network/volume |

Other

| Key | Action | |-----|--------| | / | Search/Filter | | r | Refresh data | | ? | Show help |

Development

# Run in development mode with hot reload
pnpm dev

# Type check
pnpm run typecheck

# Lint
pnpm run lint

# Run tests
pnpm test

# Run tests with coverage
pnpm run test:coverage

# Format code
pnpm run format

Architecture

The application is built with:

• Ink: React for CLI applications
• TypeScript: Type-safe development
• React Hooks: State management with useState, useCallback, useEffect

Project Structure

src/
├── components/      # React components (views, dialogs, UI elements)
├── hooks/           # Custom React hooks
├── services/        # Container CLI wrapper and utilities
├── types/           # TypeScript type definitions
└── index.tsx        # Application entry point

Key Files

| File | Description | |------|-------------| | src/index.tsx | Entry point with health check | | src/components/App.tsx | Main application component | | src/services/container-cli.ts | macOS container CLI wrapper | | src/hooks/useContainerData.ts | Data fetching and state | | src/hooks/useKeyboard.ts | Centralized keyboard handling | | src/types/index.ts | TypeScript interfaces |

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feat/amazing-feature)
3. Make your changes
4. Run validation:

   pnpm run typecheck
   pnpm run lint
   pnpm test

5. Commit using Conventional Commits:

   git commit -m "feat: add amazing feature"

6. Push and open a Pull Request

Commit Message Format

This project uses conventional commits enforced by commitlint:

• feat: New feature
• fix: Bug fix
• docs: Documentation changes
• style: Code style changes (formatting, etc.)
• refactor: Code refactoring
• perf: Performance improvements
• test: Test additions or corrections
• build: Build system changes
• ci: CI configuration changes
• chore: Maintenance tasks

License

MIT