Cloudflare KV Manager

🎯 Live Demo | 🐳 Docker Hub | 📦 GitHub

✨ Major Features

Namespace Management: Complete CRUD operations including create, list, rename, and delete KV namespaces with intuitive interface. Namespace info viewing with metadata and statistics. Bulk namespace operations with progress tracking.

Key Operations: Full key management with create, read, update, and delete operations. TTL support for automatic key expiration with visual countdown timers. Paginated key browsing (configurable page size) for efficient navigation through large datasets. Key value editor with syntax highlighting and formatting support. Metadata and tags system allowing custom annotations and searchability.

Cross-Namespace Search: Powerful search functionality across all namespaces with smart filtering by key name, tags, metadata, or content. Advanced filtering with multiple criteria and logical operators. Search results aggregation showing matches across namespaces with context.

Bulk Operations: Bulk delete up to 10,000 keys at once via REST API with progress tracking. Bulk tagging to apply metadata across multiple keys simultaneously. Batch operations with transactional guarantees where available. Async operation handling with real-time progress indicators.

Automatic Backup System: Single-version automatic backup before every update and delete operation. Backup naming convention preserving original key identity (__backup__:original-key). 24-hour retention with automatic expiration via TTL. One-click restore functionality to recover from accidental changes.

Audit Logging: Comprehensive operation tracking with full user attribution for accountability. All operations recorded with timestamp, user, action, and result details. User activity history and audit log querying with date range filters. Export capabilities for compliance and analysis purposes.

Color Organization System: Visual color tagging at both namespace and key level using a carefully curated 27-color palette organized by hue. Color picker dropdowns with fixed positioning, optimistic UI updates with automatic rollback on API failure, and full WCAG accessibility including aria-labels, keyboard navigation, and focus indicators. Use cases include organizing by environment (production, staging, development), grouping related keys by feature, and visually distinguishing critical data.

Enhanced Create Key Dialog: Full metadata support when creating new keys, including KV Native Metadata (JSON) field with live validation and formatting, inline tags section with keyboard support (Enter to add), and Custom Metadata (JSON) for D1-backed searchable metadata. Streamlined workflow reduces steps for bulk key creation.

Modern UI built with shadcn/ui components and Tailwind CSS, featuring dark/light theme support with system-aware detection and manual toggle persistence. Responsive design optimized for desktop, tablet, and mobile devices with intuitive navigation between namespaces and keys. Real-time progress indicators for long-running operations and comprehensive error reporting with user-friendly messages.

🔧 Technical Stack

Frontend: React, TypeScript, Vite, Tailwind CSS, shadcn/ui components

Backend: Cloudflare Workers Runtime API, KV storage for data, D1 database for metadata and audit logs, Durable Objects for coordination and bulk operations orchestration, TypeScript

Authentication: Cloudflare Access Zero Trust integration with JWT validation, support for multiple identity providers (GitHub OAuth, Google, Azure AD, email), local development mode with mock data

🚀 Deployment & Security

Deploy to Cloudflare Workers with Workers.dev subdomain or custom domains with automatic edge scaling. Docker images available with multi-architecture support (linux/amd64, linux/arm64) and ~120MB compressed size. Kubernetes-ready deployment configurations included. Security features include JWT validation on all requests, session management with configurable timeouts, CORS protection for cross-origin requests, rate limiting to prevent abuse, request validation and sanitization, and container security with non-root execution on minimal Alpine Linux base.

📚 Getting Started

Local Development - No authentication required for localhost, mock data included, works without Cloudflare credentials:

Step 1: Clone and setup

git clone https://github.com/neverinfamous/kv-manager.git

cd kv-manager

Step 2: Install dependencies

npm install

Step 3: Copy environment file

cp .env.example .env

Step 4: Start development servers (in separate terminals)

Terminal 1 - Frontend:

npm run dev

Terminal 2 - Worker API:

npx wrangler dev --config wrangler.dev.toml --local

Access the application at http://localhost:5173

Docker:

Step 1: Pull the image

docker pull writenotenow/kv-manager:2.1.0

Step 2: Run the container (replace with your actual Cloudflare credentials)

docker run -d \
  -p 8080:8080 \
  -e ACCOUNT_ID=your_cloudflare_account_id \
  -e API_KEY=your_cloudflare_api_token \
  -e TEAM_DOMAIN=https://yourteam.cloudflareaccess.com \
  -e POLICY_AUD=your_cloudflare_access_aud_tag \
  --name kv-manager \
  writenotenow/kv-manager:latest

Access the application at http://localhost:8080

Production Deployment:

Step 1: Configure Wrangler

cp wrangler.toml.example wrangler.toml

Then edit wrangler.toml with your settings.

Step 2: Create metadata database

npx wrangler d1 create kv-manager-metadata

Step 3: Initialize schema

npx wrangler d1 execute kv-manager-metadata --remote --file=worker/schema.sql

Step 4: Set secrets (run each command and enter the value when prompted)

npx wrangler secret put ACCOUNT_ID

npx wrangler secret put API_KEY

npx wrangler secret put TEAM_DOMAIN

npx wrangler secret put POLICY_AUD

Step 5: Build the project

npm run build

Step 6: Deploy to Cloudflare Workers

npx wrangler deploy

📋 API Endpoints

The application provides 22+ RESTful API endpoints for comprehensive KV management:

• Namespace Operations - List, create, delete, rename, and get namespace info
• Key Operations - List (paginated), create/update, read, delete, and bulk delete keys
• Metadata & Tags - Get/update key metadata, bulk tag operations across keys
• Color Management - Get/update namespace colors, get/update key colors
• Search - Cross-namespace key search with advanced filtering
• Backup & Recovery - Check backup existence and restore from backups
• Audit - Query audit logs by namespace or user with filtering

🎯 Key Technical Details

KV is eventually consistent with up to 60-second propagation globally. List operations are limited to 1000 keys per call requiring cursor pagination. REST API bulk operations are limited to 10,000 keys using Durable Objects for coordination. Native KV metadata is limited to 1024 bytes but supplemented with D1 storage for extended metadata and tags. Write rate is limited to 1 per second per key with batching and throttling for bulk operations.

Automatic backups are triggered on every update/delete, stored as __backup__:original-key in the same namespace. 24-hour TTL ensures cleanup without manual intervention. One-click restore is available with a single API call.

The D1 metadata schema includes: namespaces table for tracking access times and metadata, key_metadata table for tags and custom metadata, and audit_log table for recording operations with user attribution.

🐛 Known Limitations

KV's eventual consistency means keys may not immediately appear after creation - the UI displays replication status. Maximum 1,000 keys per API list call requires pagination for large namespaces - implemented automatically. Backup system stores single version - multiple versions require external versioning systems. Bulk operations limited to 10,000 keys per request - larger operations require manual chunking.

📊 Statistics

40+ React components, 18+ API endpoints, 8,000+ lines of code, ~120MB Docker image size. Supports Web, Docker, and Kubernetes platforms. Compatible with all modern browsers (Chrome, Firefox, Safari, Edge) and all major Cloudflare Access identity providers.

🏆 Why This Release Matters

KV Manager provides essential tooling for developers managing Cloudflare Workers KV at scale. Whether you're storing configuration, session data, cache, or any other key-value information, KV Manager makes it dramatically easier to manage, search, and audit your data. The combination of bulk operations, audit logging, and automatic backups provides both operational efficiency and compliance capabilities suitable for production use.

Pro Tip: Use tags to organize keys logically and enable advanced searching across namespaces. Combined with bulk tagging, this becomes a powerful way to manage related keys at scale!

🤝 Contributing

We welcome contributions from the community! Fork the repository, create a feature branch, commit your changes, and open a Pull Request. Bug reports, feature requests, and documentation improvements are all appreciated. See CONTRIBUTING.md for detailed guidelines.

📞 Support & Resources

Project Links: GitHub Repository | Live Demo | Docker Hub | Email: admin@adamic.tech

🙏 Acknowledgments

Special thanks to Cloudflare for Workers, KV, D1, and Durable Objects platform; React Team for React 19; shadcn for the UI component library; Vite Team for the incredible build tool; and all community contributors for their feedback and support.

📄 License

KV Manager is released under the MIT License.

Thank you to everyone in the Cloudflare community for your interest! We're excited to see how you use KV Manager to simplify your Workers KV management. Built with ❤️ for the Cloudflare community.