📜 Description of the cpdsl Command (cptd >= v2.0.5)

Name: cpdsl
Role: Interpreter for declarative .dsl scripts enabling sequential execution of installed cptd commands
Platform Support: Cross-platform (Linux / Windows / macOS)
Format: Step-based YAML scenario files

---

🚀 What Is cpdsl and Why Does It Matter?

cpdsl is the official scenario interpreter within the CPTD CLI platform. It reads YAML-based workflows line by line, step by step — transforming manual command sequences into structured, repeatable, and secure automation pipelines.

---

🧠 Why Use cpdsl?

• Automate routine procedures using registered cptd commands
• Replace unreliable shell scripts with validated YAML instructions
• Ensure portability — a single .dsl file can run anywhere
• Achieve full transparency, reproducibility, and structured logging
• Centralize complex operations such as backups, encryption, uploads, logging, and more

---

📌 Why It’s Convenient

• A single .dsl file encapsulates an entire workflow
• Easily share automation logic as modules or assets
• Seamless GUI integration (e.g., a “Run Backup” button)
• Easy debugging and reusability of automation logic

---

📊 Advantages of the DSL Approach

Feature	Advantage
📦 Uniformity	All commands are launched through a consistent interface
♻️ Reusability	One DSL file can run on thousands of machines or via scheduled tasks
📋 Self-documenting	DSL reads like a technical spec or execution plan
🧱 Extensibility	Future-ready: if, loop, include, when and more are possible
🔐 Security	Immune to shell injection, eval, or accidental rm -rf disasters
🧠 Cross-platform	Same .dsl works on Windows, Linux, and remote servers
🧰 Integratable	Can be invoked from UI buttons, web dashboards, apps, or triggers

---

📂 Example Command

cptd cpdsl run backup.dsl --log out.txt --strict --wait-all --summary

---

🏁 Conclusion

cpdsl isn’t just syntax — it’s structure. It’s automation strategy with clarity and control.

Forget chaotic bash chains and cryptic && sequences.
Write readable, testable, extensible workflows that evolve with your project.

cpdsl — Structure your CLI. Define your workflows. Automate with precision.

---

📘 YAML Scenario Guide for cpdsl

cpdsl is a YAML-based scenario interpreter for sequential and parallel command execution within the CPTD CLI system.
Scenarios let you combine complex processes (archiving, encryption, uploading, testing, etc.) into a single descriptive file.

---

🧱 Basic File Structure (.dsl)

name: "Scenario Name"
description: "Short description of purpose"

steps:
  - name: "Step Name"
    command: "command_name"
    args:
      --flag1: value
      --flag2: true
    async: true
    depends_on: "step_name"

---

🧩 Field Descriptions

🔹 Top-Level Fields:

Field	Type	Purpose
name	string	Human-readable scenario name
description	string	Short summary
steps	list	Array of step definitions (see below)

---

🔹 Inside steps[]:

Field	Type	Required	Purpose
name	string	No	Step name (for display and depends_on)
command	string	✅ Yes	Name of the registered CPTD command
args	dict --flag: val	No	Arguments for the command. true → flag only; false → ignored
async	bool	No	If true, runs the step in the background
depends_on	string / list	No	Dependencies. Runs only after specified step(s) complete

---

🔹 Special Feature: Environment Variables

Instead of a fixed value, you can reference an environment variable:

args:
  --password-env: SFTP_PASS

Inside cpdsl, this becomes:

--password-env <value of SFTP_PASS>

---

✅ Example of a Simple Scenario

name: "Backup"
description: "Mount, archive, and upload archive"

steps:
  - name: "Mount"
    command: "cpdisk"
    args:
      --mount: true
      --file: "vault.hc"

  - name: "Archive"
    command: "compress"
    args:
      --input: "/vault/data"
      --output: "/tmp/data.zip"
    depends_on: "Mount"

  - name: "Upload"
    command: "uploader"
    args:
      --file: "/tmp/data.zip"
      --target: "sftp://host/upload"
      --password-env: SFTP_PASS
    async: true
    depends_on: "Archive"

---

🧪 Running a Scenario

cptd cpdsl run backup.dsl --log log.txt --strict --wait-all --summary

🎛 Run Arguments:

Argument	Purpose
--log <file>	Save execution log
--strict	Stop on first error
--wait-all	Wait for all async: true steps to finish
--summary	Print a summary table of step statuses at the end

---

📋 Example of Summary Output (--summary)

Summary:
✔ Step 1 - Mount                [OK]
✔ Step 2 - Archive              [OK]
✔ Step 3 - Upload               [ASYNC]

---

⚠️ Error Handling

Scenario	Default Behavior	With --strict
depends_on references unknown step	Error	Error
Step exits with non-zero code	Continues	Stops
Async step fails	Logs the error	Stops

---

🚀 Writing Tips

• Always assign a unique name: to each step
• Use depends_on to define logical order
• Use async: true for background tasks
• Store your .dsl files in scripts/ or scenarios/ for project structure