djangoplay-cli

Maintained by DjangoPlay

djangoplay-cli is a developer command-line interface for managing local development environments within the DjangoPlay ecosystem.

The CLI simplifies common developer workflows such as:

• starting HTTP and HTTPS development servers
• regenerating SSL certificates
• managing Celery workers
• validating environment dependencies
• resetting development services
• streaming application logs
• orchestrating local development processes

The goal is to provide a simple, predictable, and portable developer tool without introducing complex infrastructure dependencies.

---

Philosophy

This project follows several guiding principles:

• Minimal configuration
• No secrets in the repository
• Clear command structure
• Stable developer experience
• Incremental releases
• Developer-first ergonomics

The CLI is designed to remove repetitive setup tasks so developers can focus on application development instead of environment management.

---

Supported Platforms

Platform	Status
macOS	Supported
Linux	Supported
Ubuntu	Supported
Windows (WSL)	Supported
Windows native	Limited

---

Installation

Install from PyPI:

pip install djangoplay-cli

Verify installation:

dplay --version

Example output:

1.0.5

---

CLI Overview

dplay
├── http
├── ssl
├── certs
├── logs
│
├── dev
│    └── worker
│
└── system
     ├── doctor
     └── reset

---

Development Commands

These commands manage the Django development environment.

---

Start HTTP development server

dplay http

Performs the following automatically:

• encrypts environment variables from ~/.dplay/
• flushes Redis cache
• collects static files
• restarts Celery worker and beat
• waits until Celery is ready
• stops any existing Django server on the configured port
• opens the browser
• starts the Django development server

The server URL is automatically derived from ~/.dplay/config.yaml.

Example:

http_protocol: http
http_port: 3333
http_url: localhost

---

Start HTTPS development server

dplay ssl

Performs the same startup sequence as dplay http, plus:

• checks for SSL certificates under ~/.dplay/ssl/
• generates certificates if necessary
• automatically trusts certificates on macOS, Linux, and WSL
• launches Django using runserver_plus

The HTTPS URL is read from your configuration.

If certificates cannot be generated:

TLS certificate unavailable. Use dplay http

---

Start Celery worker

dplay dev worker

Starts the Celery worker in the foreground.

---

Regenerate SSL certificates

dplay certs

Regenerates SSL certificates from the current configuration without restarting the development server.

Useful after adding new subdomains:

subdomains:
  extra_domains:
    - issues.localhost
    - docs.localhost

Then run:

dplay certs
dplay ssl

The generated certificate is automatically trusted on supported platforms.

---

Stream application logs

dplay logs
dplay logs [APP]

Streams and pretty-prints application logs with colorized output by log level.

Examples:

dplay logs
dplay logs users
dplay logs mailer --level ERROR
dplay logs django --no-follow -n 100

Options:

Option	Default	Description
APP	django	Application log to stream
--lines, -n	50	Historical lines shown initially
--level, -l	—	Filter by log level
--follow / --no-follow	follow	Stream new log entries

Applications are discovered automatically from backend/logs/.

---

System Commands

Environment diagnostics

dplay system doctor

Checks:

• Python version
• Redis availability
• PostgreSQL availability
• Celery installation

---

Reset development environment

dplay system reset

Performs:

• stops Celery workers
• stops Celery beat
• flushes Redis

---

CLI Help

dplay --help

Development commands:

dplay dev --help

System commands:

dplay system --help

---

Project Structure

djangoplay-cli/

dplay/
├── commands/
├── core/
├── environment/
└── utils/

Architecture

Layer	Responsibility
CLI Commands	User-facing commands
Core	Repository detection, process management
Environment	Environment validation
Utils	SSL, logging, Redis, browser, startup orchestration

The modular architecture keeps the CLI maintainable while allowing new commands to be added with minimal coupling.

---

Development Setup

Clone the repository:

git clone https://github.com/binaryfleet/djangoplay-cli.git
cd djangoplay-cli

Install locally:

pip install -e .

Install development tools:

pip install ruff pytest

Run linting:

ruff check .

Run tests:

pytest

---

Security

This project follows strict security practices:

• no credentials stored in the repository
• no secrets generated automatically
• no credentials written to disk
• SSL certificates generated only for local development

---

Versioning

This project follows Semantic Versioning.

v0.x  Experimental
v1.x  Stable

---

License

Licensed under the MIT License.

See the LICENSE file for details.