Metadata-Version: 2.4
Name: djangoplay-cli
Version: 1.0.3rc1
Summary: CLI tools for DjangoPlay developers. A lightweight command-line interface for managing local development environments within the DjangoPlay ecosystem.
Author: BinaryFleet
License-Expression: MIT
Project-URL: Homepage, https://github.com/binaryfleet/djangoplay-cli
Project-URL: Repository, https://github.com/binaryfleet/djangoplay-cli
Project-URL: Issues, https://github.com/binaryfleet/djangoplay-cli/issues
Project-URL: Documentation, https://github.com/binaryfleet/djangoplay-cli#readme
Keywords: django,cli,developer-tools,djangoplay,devtools,celery,ssl,local-development
Classifier: Development Status :: 5 - Production/Stable
Classifier: Framework :: Django
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Utilities
Classifier: Environment :: Console
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: typer>=0.9
Requires-Dist: rich>=13
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Dynamic: license-file

# djangoplay-cli

![PyPI](https://img.shields.io/pypi/v/djangoplay-cli)
![Python](https://img.shields.io/pypi/pyversions/djangoplay-cli)
![License](https://img.shields.io/pypi/l/djangoplay-cli)
![Django](https://img.shields.io/badge/django-4.2-green)
![Lint](https://img.shields.io/badge/lint-ruff-informational)


**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 the development server
- managing Celery workers
- validating environment dependencies
- resetting development services
- 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:

```bash
pip install djangoplay-cli
```

Verify installation:

```bash
dplay --version
```

Example output:

```
1.0.3
```

---

# CLI Overview

The CLI is organized into command groups.

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

---

# Development Commands

These commands manage the Django development environment.

---

### Start HTTP development server

```
dplay dev http
```

Performs the following steps 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 port
* opens the browser
* starts the Django HTTP development server

Server URL:

```
http://localhost:3333
```

---

### Start HTTPS development server

```
dplay dev ssl
```

Performs the same steps as `dplay dev http`, plus:

* checks for SSL certificates under `~/.dplay/ssl/`
* generates self-signed certificates if absent
* trusts the certificate in the macOS System Keychain automatically (macOS only)
* starts the server via `runserver_plus` with the certificate and key
* trusts the certificate in the system keychain automatically
  (macOS Keychain, Linux system store, or Windows store via WSL)

Server URL:

```
https://localhost:9999
```

> If SSL certificates cannot be created, the CLI exits with:
> `TLS certificate unavailable. Use dplay dev http`

---

### Default command

Running `dplay dev` without a subcommand starts the HTTP server:

```
dplay dev
```

---

### Start Celery worker

```
dplay dev worker
```

Starts the Celery worker for the DjangoPlay application in the foreground.

---

### Regenerate SSL certificates
```
dplay dev certs
```

Regenerates local SSL certificates from the current `~/.dplay/config.yaml`.
Use this after adding new subdomains to `subdomains.extra_domains` in config.

Automatically trusts the new certificate in the system keychain on macOS,
Linux, and WSL. No server restart required.

To add subdomain coverage, update `~/.dplay/config.yaml`:
```yaml
subdomains:
  extra_domains:
    - issues.localhost
    - docs.localhost
```

Then run:
```
dplay dev certs
dplay dev ssl
```
---

# System Commands

System commands validate and reset the development environment.

### Run environment diagnostics

```
dplay system doctor
```

Checks:

* Python version
* Redis availability
* PostgreSQL availability
* Celery installation

Example output:

```
Environment Diagnostics

✔ Python version OK
✔ Redis reachable
✔ Postgres reachable
✔ Celery available
```

---

### Reset development environment

```
dplay system reset
```

Actions performed:

* stop running Celery workers
* stop Celery beat processes
* flush Redis cache

---

# Logs

Display development logs.

```
dplay logs
```

(Currently reserved for future improvements.)

---

# CLI Help

Show CLI help:

```
dplay --help
```

Show development commands:

```
dplay dev --help
```

Show system commands:

```
dplay system --help
```

---

# Project Structure

```
djangoplay-cli/

dplay/
  commands/
  core/
  environment/
  utils/
```

### Architecture Layers

| Layer        | Responsibility                        |
| ------------ | ------------------------------------- |
| CLI Commands | user-facing commands                  |
| Core         | repository detection, process manager |
| Environment  | environment validation                |
| Utils        | reusable helpers                      |

This modular architecture keeps the CLI maintainable as new features are added.

---

# Development Setup

Clone repository:

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

Install in editable mode:

```
pip install -e .
```

Install development tools:

```
pip install ruff pytest
```

Run lint checks:

```
ruff check .
```

Run tests:

```
pytest
```

---

# Security Principles

This project follows strict security practices:

* no credentials stored in the repository
* CLI never generates secrets automatically
* CLI never writes credentials to disk

---

# Versioning

This project follows **Semantic Versioning**.

```
v0.x  → experimental development
v1.x  → stable production releases
```

---

# License

This project is licensed under the **MIT License**.

See the [LICENSE](LICENSE) file for details.
