Operations

Operations are the fundamental building blocks in Dyngle. An operation is a named sequence of steps that execute commands.

Basic Structure

Operations are defined under dyngle: in the configuration. The simplest form is a YAML array of command steps:

dyngle:
  operations:
    hello:
      - echo "Hello world"
    
    build:
      - npm install
      - npm run build

Run an operation:

dyngle run hello

Operation Anatomy

Simple Array Form

For operations with just steps, use the array syntax:

dyngle:
  operations:
    init:
      - rm -rf .venv
      - python3.11 -m venv .venv
      - .venv/bin/pip install --upgrade pip poetry

Extended Form

When you need additional attributes, use the extended form with a steps: key:

dyngle:
  operations:
    build:
      description: Build the project for production
      access: public
      return: build-info
      expressions:
        build-time: "datetime.now()"
      steps:
        - npm install
        - npm run build
        - echo "{{build-time}}" => build-info

Operation Attributes

description

An optional description that appears in dyngle list-operations output:

dyngle:
  operations:
    deploy:
      description: Deploy to production
      steps:
        - sub: build
        - aws s3 sync ./dist s3://my-bucket/

access

Controls visibility and usage. See Access Control for details.

public (default) - Can be run directly, exposed via MCP, listed in operations
private - Can only be called as a sub-operation

return

Specifies what value to return. See Return Values for details.

dyngle:
  operations:
    get-temperature:
      return: temp
      steps:
        - curl -s "https://api.example.com/weather" => weather-data
        - weather-data -> jq -r '.temperature' => temp

expressions

Local expressions available only within this operation. See Expressions for details.

dyngle:
  operations:
    greet:
      expressions:
        greeting: "'Hello ' + name + '!'"
      steps:
        - echo "{{greeting}}"

values

Local values available only within this operation. See Data and Templates for details.

dyngle:
  operations:
    deploy:
      values:
        environment: production
        region: us-west-2
      steps:
        - echo "Deploying to {{environment}} in {{region}}"

Command Syntax

Operation steps use shell-like syntax but are not executed in a shell:

Commands are parsed and executed directly by Python's subprocess.run()
Shell-specific features like |, >, &&, and $VARIABLE won't work
Use Dyngle's data flow operators instead

Works:

- echo "Hello world"
- npm install
- python script.py --arg value

Doesn't work (shell syntax):

- echo "Hello" | grep Hello  # Use data flow operators instead
- export VAR=value           # Use expressions or values instead
- ls > files.txt             # Use data flow operators instead

YAML Syntax for Special Characters

When command arguments contain special characters like colons (:) that YAML interprets as syntax, use YAML's multiline string syntax:

Problem - colons in JSON:

- echo '{"temperature": 72}' => data  # YAML parsing error!

Solution - use multiline syntax:

- >-
  echo '{"temperature": 72}' => data

The >- indicator tells YAML to treat the following indented text as a single-line string, preventing colon interpretation issues.

Examples

Development workflow

dyngle:
  operations:
    test:
      description: Run the test suite
      steps:
        - pytest --cov=src tests/
        - coverage report
    
    lint:
      description: Check code style
      steps:
        - black --check src/
        - flake8 src/
    
    ci:
      description: Run all checks
      steps:
        - sub: test
        - sub: lint

Data processing

dyngle:
  operations:
    process-data:
      return: result
      steps:
        - curl -s "https://api.example.com/data" => raw-data
        - raw-data -> jq '.items' => filtered
        - filtered -> python process.py => result