docs - inbuilt documentation or help

Author: YashashavGoyal

app/commands/__init__.py

@@ -7,6 +7,7 @@
 from .shell import shell
 from .down import down
 from .status import status
+from .docs.docs import docs
 
 __all__ = [
     "init",
@@ -17,5 +18,6 @@
     "logs",
     "shell",
     "down",
-    "status"
+    "status",
+    "docs"
 ]

app/commands/docs/content/clone.md

@@ -0,0 +1,35 @@
+# mate clone
+
+The `clone` command allows you to download a Git repository to your local machine. DevMate handles destination path logic automatically if you don't specify one, following standard naming conventions.
+
+## Detailed Description
+`mate clone` uses Git to download the specified repository. If no directory is provided, it extracts the repository name from the URL and creates a folder with that name in the current directory. It is the fundamental first step before running `mate up` or other management commands.
+
+## Usage
+`mate clone <URL> [OPTIONS]`
+
+## Arguments & Options
+| Flag | Description |
+|------|-------------|
+| `URL` | The Git URL of the repository (required). |
+| `-d`, `--dir` | Custom directory path where the repo will be cloned. |
+
+## Examples
+
+### 1. Default Logic (Automatic Naming)
+Clones the repository and names the folder after the repo name (e.g., `my-app`).
+```bash
+mate clone https://github.com/user/my-app.git
+```
+
+### 2. Specific Directory
+Clones the repository into a predetermined folder structure.
+```bash
+mate clone https://github.com/user/my-app.git --dir ./projects/client-a
+```
+
+### 3. SSH Support
+Works with SSH URLs if your system is configured with Git keys.
+```bash
+mate clone git@github.com:user/my-app.git
+```

app/commands/docs/content/deploy.md

@@ -0,0 +1,44 @@
+# mate deploy
+
+The `deploy` command is the fastest way to get a project running. it combines `clone` and `up` into a single atomic operation, including automatic environment detection and health checks.
+
+## Detailed Description
+When you run `deploy`, DevMate:
+1. Clones the repository to your local machine.
+2. Enters the project directory (or a specified sub-location).
+3. Detects if the project uses Docker Compose or a standalone Dockerfile.
+4. Spins up the services.
+5. Performs immediate health checks to ensure the application is ready.
+
+## Usage
+`mate deploy <REPO_URL> [OPTIONS]`
+
+## Arguments & Options
+| Flag | Description |
+|------|-------------|
+| `REPO_URL` | The Git URL to clone (required). |
+| `-n`, `--name` | Custom name for the cloned folder. |
+| `-b`, `--branch` | Specific branch to clone (e.g., `main`, `staging`). |
+| `-p`, `--port` | Port mappings for Dockerfile projects (`HOST:CONTAINER`). |
+| `-l`, `--location` | Subdirectory inside the repo where config files are found (default `.`). |
+| `-f`, `--force` | Force rebuild of images and restart. |
+
+## Examples
+
+### 1. Docker Compose Scenario (Default)
+Deploys a multi-container stack from a standard repository.
+```bash
+mate deploy https://github.com/example/api-stack.git
+```
+
+### 2. Dockerfile Scenario (with Port Mapping)
+Deploys a single service and maps it to a specific local port.
+```bash
+mate deploy https://github.com/example/web-app.git --port 8080:80
+```
+
+### 3. Custom Branch and Sub-location
+Deploys the `dev` branch and looks for configuration in the `./backend` folder.
+```bash
+mate deploy https://github.com/example/monorepo.git --branch dev --location ./backend
+```

app/commands/docs/content/down.md

@@ -0,0 +1,38 @@
+# mate down
+
+The `down` command stops and cleans up your development environment. It is designed to safely terminate processes and optionally remove transient assets like volumes and images.
+
+## Detailed Description
+`mate down` automatically detects your environment type. For Compose projects, it stops and removes containers and networks. For standalone containers, it terminates the specific process. Use this when you want to free up system resources or reset your environment.
+
+## Usage
+`mate down [OPTIONS]`
+
+## Options
+| Flag | Description |
+|------|-------------|
+| `-p`, `--project-path` | Path to the project. DevMate detects the config here. |
+| `-c`, `--container-name` | Explicitly stop a container by name, ignoring project logic. |
+| `-v`, `--remove-volumes` | Remove named and anonymous volumes (use with caution). |
+| `-i`, `--remove-images` | Remove images used by the services. |
+| `-o`, `--remove-orphans` | Clean up containers not defined in the current compose file. |
+
+## Examples
+
+### 1. Docker Compose Cleanup
+Stops all services defined in the current directory's Compose file.
+```bash
+mate down
+```
+
+### 2. Dockerfile Cleanup (Full Reset)
+Stops the container and removes its images and volumes.
+```bash
+mate down -v -i
+```
+
+### 3. Direct Container Stop
+Stops a specific container named "legacy-db" without needing a manifest file.
+```bash
+mate down --container-name legacy-db
+```

app/commands/docs/content/health.md

@@ -0,0 +1,38 @@
+# mate health
+
+The `health` command verifies that your application is not just running, but actually responding to requests.
+
+## Detailed Description
+`mate health` performs active polling against your application's endpoints. It supports both HTTP (for web apps) and TCP (for databases/internal services). It includes built-in retry logic and progress tracking to handle applications with slow startup times.
+
+## Usage
+`mate health [OPTIONS]`
+
+## Options
+| Flag | Description |
+|------|-------------|
+| `-u`, `--url` | Base URL (e.g., `http://localhost`). |
+| `-p`, `--path` | Endpoint path (default: `/`). |
+| `-P`, `--port` | Port to check. |
+| `-r`, `--max-retries` | How many times to try before giving up (default: 3). |
+| `-t`, `--timeout` | Seconds to wait for each request. |
+
+## Examples
+
+### 1. Web Service Check
+Checks if your frontend is serving traffic on the root path.
+```bash
+mate health --port 3000
+```
+
+### 2. API Health Endpoint
+Verifies a specific internal status endpoint with multiple retries.
+```bash
+mate health -P 8080 -p /api/v1/health --max-retries 10
+```
+
+### 3. Remote Service Audit
+Checks the health of an external or staging URL.
+```bash
+mate health --url http://staging.myapp.com --timeout 10
+```

app/commands/docs/content/init.md

@@ -0,0 +1,39 @@
+# mate init
+
+The `init` command ensures your local machine is ready for development using DevMate. It acts as a "Doctor" check for your dev environment.
+
+## Detailed Description
+`mate init` audits your system for three critical dependencies:
+- **Git**: Required for `clone` and `deploy`.
+- **Docker**: Required for all container management.
+- **Python**: Required for internal CLI logic.
+
+If any tool is missing, DevMate doesn't just error out—it provides official download links and installation guidance tailored to your needs.
+
+## Usage
+`mate init [OPTIONS]`
+
+## Options
+| Flag | Description |
+|------|-------------|
+| `-v`, `--verbose` | Show detailed paths and versions of detected tools. |
+
+## Examples
+
+### 1. Standard Environment Check
+The first command any new DevMate user should run.
+```bash
+mate init
+```
+
+### 2. Verbose Audit
+Useful if you have multiple versions of tools and need to know which one `mate` found.
+```bash
+mate init --verbose
+```
+
+### 3. Alias Support
+You can also run this using the `doctor` alias for a friendlier feel.
+```bash
+mate doctor
+```

app/commands/docs/content/logs.md

@@ -0,0 +1,37 @@
+# mate logs
+
+The `logs` command streams the output of your application to your terminal, making it easy to monitor activity and catch errors as they happen.
+
+## Detailed Description
+DevMate `logs` integrates with both Docker Compose and standalone containers. It supports "follow" mode for real-time monitoring and allows you to limit the output history using the "tail" option to avoid terminal clutter.
+
+## Usage
+`mate logs [OPTIONS]`
+
+## Options
+| Flag | Description |
+|------|-------------|
+| `-f`, `--follow` | Stream logs in real-time until interrupted (Ctrl+C). |
+| `-t`, `--tail` | Number of recent lines to display (default: 100). |
+| `-c`, `--container` | Explicitly fetch logs for a specific container name. |
+| `-p`, `--path` | Project path for fetching Compose-wide logs. |
+
+## Examples
+
+### 1. Project Monitoring (Compose)
+Follows logs from ALL services in your current stack simultaneously.
+```bash
+mate logs -f
+```
+
+### 2. Debugging a Specific Service
+Shows the last 500 lines for a specific container.
+```bash
+mate logs --container web-api --tail 500
+```
+
+### 3. Quick Inspection
+Checks the recent history of the current folder's project without streaming.
+```bash
+mate logs
+```

app/commands/docs/content/main.md

@@ -0,0 +1,76 @@
+# DevMate (`mate`) — The Developer's Companion
+
+Welcome to the official documentation for **DevMate**. 
+
+DevMate is a high-performance, developer-centric orchestration tool designed to bridge the gap between your local source code and a fully functional containerized environment.
+
+---
+
+## 🛠️ Commands & Examples
+
+Use `mate docs <command>` for even more specialized guides.
+
+### 1. `init` (System Audit)
+Ensure your environment is ready.
+- **Example**: `mate init`
+- **Verbose**: `mate init --verbose`
+- **Alias**: `mate doctor`
+
+### 2. `clone` (Smart Fetch)
+Download repositories with automatic naming.
+- **Default**: `mate clone https://github.com/user/my-app.git`
+- **Custom Dir**: `mate clone <URL> --dir ./src`
+- **SSH**: `mate clone git@github.com:user/repo.git`
+
+### 3. `up` (Orchestrate)
+Build and start your services.
+- **Compose**: `mate up` (auto-detects `compose.yaml`)
+- **Dockerfile**: `mate up --port 8080:80` (auto-maps local port)
+- **Force**: `mate up --force --pull always` (fresh build)
+
+### 4. `deploy` (One-Touch)
+Clone and start in one command.
+- **Compose Stack**: `mate deploy https://github.com/user/api-stack.git`
+- **Single Service**: `mate deploy <URL> --port 3000:3000`
+- **Branch/Sub-location**: `mate deploy <URL> --branch dev --location ./app`
+
+### 5. `status` (Monitor)
+Real-time dashboard of your containers.
+- **Standard**: `mate status`
+- **Inspection**: `mate status --volume --health`
+- **Filtered**: `mate status --stopped --all`
+
+### 6. `shell` (Interact)
+Instant terminal access into containers.
+- **Interactive**: `mate shell` (picks best container)
+- **Direct**: `mate shell --name redis-service`
+- **Custom Shell**: `mate shell --sh /bin/bash`
+
+### 7. `logs` (Stream)
+Monitor application output.
+- **Follow All**: `mate logs -f`
+- **Service Specific**: `mate logs --container api-gw --tail 200`
+- **Quick Check**: `mate logs`
+
+### 8. `health` (Audit)
+Validate endpoint responsiveness.
+- **Local HTTP**: `mate health --port 8080`
+- **Internal API**: `mate health -P 5000 -p /health --max-retries 5`
+- **TCP Check**: `mate health --url tcp://localhost:5432`
+
+### 9. `down` (Cleanup)
+Safe environment shutdown.
+- **Compose Reset**: `mate down`
+- **Full Removal**: `mate down -v -i` (deletes volumes/images)
+- **Specific Container**: `mate down --container-name test-db`
+
+---
+
+## Quick Start - The most common workflow
+```bash
+mate init                                           # 1. Check system
+mate deploy https://github.com/user/project        # 2. Get it running
+mate status                                         # 3. Verify services
+```
+for more workflows run `mate docs workflow`
+*DevMate — Build faster, debug less.*

app/commands/docs/content/shell.md

@@ -0,0 +1,36 @@
+# mate shell
+
+The `shell` command provides instant access into any running container, allowing you to run management commands, inspect logs, or debug the environment directly.
+
+## Detailed Description
+`mate shell` is your primary tool for "Inside-the-box" debugging. It automatically detects the most relevant container in your current project directory. If your project has multiple containers (Compose), it provides an interactive selection menu.
+
+## Usage
+`mate shell [OPTIONS]`
+
+## Options
+| Flag | Description |
+|------|-------------|
+| `-n`, `--name` | Name of the container or Compose service to connect to. |
+| `-s`, `--sh` | Shell executable to use (default: `/bin/sh`). |
+| `-p`, `--path` | Project directory for auto-detection logic. |
+
+## Examples
+
+### 1. Interactive Selection (Compose)
+If you have multiple services, DevMate will let you pick the one you want.
+```bash
+mate shell
+```
+
+### 2. Direct Container Access
+Quickly jump into a known container to check a specific file or process.
+```bash
+mate shell --name my-redis-cache
+```
+
+### 3. Custom Shell (Bash)
+Use this if the container has `bash` installed for a more feature-rich experience.
+```bash
+mate shell --sh /bin/bash
+```